> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/app-store.md).

# App Store

The App Store service provides access to iOS application data including reviews, ratings, and app metadata.

## Endpoints

| Endpoint                        | Description       | Pagination |
| ------------------------------- | ----------------- | ---------- |
| `GET /v1/app-store/reviews`     | Fetch app reviews | Standard   |
| `GET /v1/app-store/reviews/all` | Fetch all reviews | Managed    |

***

## Get Reviews

Fetch reviews for an iOS app with standard pagination.

### Request

```http
GET /v1/app-store/reviews
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter | Type    | Required | Description                                 |
| --------- | ------- | -------- | ------------------------------------------- |
| `app_id`  | string  | Yes      | App Store app ID (numeric)                  |
| `country` | string  | No       | Country code (default: `us`)                |
| `sort`    | string  | No       | Sort order: `recent`, `helpful`, `critical` |
| `limit`   | integer | No       | Results per page (default: 25, max: 100)    |
| `cursor`  | string  | No       | Pagination cursor                           |

### Example

```bash
curl "https://api.pullbay.com/v1/app-store/reviews?app_id=284882215&country=us&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "10293847561",
      "author": "HappyUser",
      "rating": 5,
      "title": "Best app ever",
      "content": "I've been using this app for years and it keeps getting better...",
      "date": "2024-01-15T10:30:00Z",
      "version": "5.2.1",
      "helpful_count": 42
    }
  ],
  "pagination": {
    "next_cursor": "eyJwYWdlIjoyLCJsaW1pdCI6MjV9",
    "has_more": true
  },
  "meta": {
    "credits_used": 1,
    "request_id": "req_abc123"
  }
}
```

### Credit cost

1 credit per page.

***

## Get Reviews (Managed)

Fetch all reviews for an iOS app in a single request. Pullbay handles pagination internally.

### Request

```http
GET /v1/app-store/reviews/all
Authorization: Bearer YOUR_API_KEY
```

### Parameters

| Parameter     | Type    | Required | Description                                 |
| ------------- | ------- | -------- | ------------------------------------------- |
| `app_id`      | string  | Yes      | App Store app ID (numeric)                  |
| `country`     | string  | No       | Country code (default: `us`)                |
| `sort`        | string  | No       | Sort order: `recent`, `helpful`, `critical` |
| `max_results` | integer | No       | Maximum results (default: all)              |

### Example

```bash
curl "https://api.pullbay.com/v1/app-store/reviews/all?app_id=284882215&country=us" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "10293847561",
      "author": "HappyUser",
      "rating": 5,
      "title": "Best app ever",
      "content": "I've been using this app for years...",
      "date": "2024-01-15T10:30:00Z",
      "version": "5.2.1",
      "helpful_count": 42
    }
  ],
  "meta": {
    "total_results": 1547,
    "pages_fetched": 62,
    "credits_used": 62,
    "request_id": "req_xyz789"
  }
}
```

### Credit cost

1 credit per page fetched internally.

***

## Review object

| Field           | Type    | Description               |
| --------------- | ------- | ------------------------- |
| `id`            | string  | Unique review identifier  |
| `author`        | string  | Reviewer username         |
| `rating`        | integer | Star rating (1-5)         |
| `title`         | string  | Review title              |
| `content`       | string  | Review body text          |
| `date`          | string  | ISO 8601 timestamp        |
| `version`       | string  | App version reviewed      |
| `helpful_count` | integer | Number of "helpful" votes |

## Finding app IDs

The `app_id` is the numeric ID in the App Store URL:

```
https://apps.apple.com/us/app/facebook/id284882215
                                        └─────────┘
                                          app_id
```

## Country codes

Use ISO 3166-1 alpha-2 codes: `us`, `gb`, `de`, `fr`, `jp`, etc.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/app-store.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.