App Store Review API Guide

When you're building or maintaining an app, understanding user feedback is critical. But manually checking App Store reviews doesn't scale. An app store review API lets you pull review data automatically, in structured format, so you can build tools, track trends, and respond to feedback at scale. This guide covers everything you need to know about Pullbay's App Store Review API and how to use it in your workflows.

---

What Is an App Store Review API?

An app store review API is a programmatic interface that lets you retrieve user reviews, ratings, and metadata directly from app stores like Apple's App Store. Instead of logging in manually and scrolling through reviews, an API lets you:

• Fetch reviews programmatically using code

• Retrieve structured data — score, text, author, date, country, version, and more

• Automate monitoring with scheduled requests

• Scale to hundreds of reviews without manual effort

• Integrate with your own tools — dashboards, alerts, CRMs, databases

Why You Need an App Store Review API

Manual review monitoring is slow and error-prone. An API solves three core problems:

1. Speed — get fresh review data in seconds, not hours

2. Scale — fetch up to 500 reviews automatically without clicking through pages

3. Integration — feed review data directly into your analytics, CRM, or alerting systems

Whether you're tracking competitor apps, monitoring your own reputation, or analysing user feedback for feature development, an API approach is faster and more reliable than manual tools.

---

How Pullbay's App Store Review API Works

Pullbay's API retrieves reviews from Apple's App Store in three steps:

1

You send a request

Specify the app you want (by numeric App Store ID or bundle ID) and any options (country, sort order, number of reviews).

2

Pullbay fetches the data

Pullbay calls Apple's review feed, handles pagination, deduplication, and normalisation, and returns a clean response.

3

You receive structured JSON

Reviews arrive as clean, normalised JSON with consistent field names, data types, and a standard response envelope.

You don't need Apple Developer credentials or App Store tokens — just your Pullbay API key and the app's ID.

---

Key Features

Two Fetch Modes

The /api/appstore/reviews endpoint supports two mutually exclusive modes:

Mode	Parameter	Behaviour
Bulk	maxItems=1–500	Pullbay paginates Apple's feed internally and returns all results in one response
Single page	page=1–10 (or omit)	Returns ~50 reviews for that page, with pagination.hasNextPage so you can iterate

maxItems and page cannot be used together in the same request.

App Identifier Options

Each request requires exactly one identifier — appId (numeric) or bundleId (reverse-domain). They cannot be used together.

Normalised Data

Review text, titles, and metadata are cleaned for consistency. Field names and types are stable across all responses.

Structured Error Responses

Errors follow the same envelope as success responses, with a clear error.code and message.

---

How to Fetch App Store Reviews: Practical Examples

You'll need:

• A Pullbay API key — get one free at pullbay.com

• An App Store numeric app ID (e.g. 284882215 for X/Twitter) or bundle ID (e.g. com.atebits.Tweetie2)

cURL

curl "https://api.pullbay.com/appstore/reviews?appId=284882215&country=us&sort=recent&maxItems=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://api.pullbay.com/appstore/reviews",
    params={
        "appId":    "284882215",   # X/Twitter
        "country":  "us",
        "sort":     "recent",      # "recent" or "helpful"
        "maxItems": 50,
    },
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=30,
)

body = response.json()
print(f"requestId: {body['requestId']}")
print(f"Retrieved {len(body['data'])} reviews — {body['pricing']['creditsCharged']} credits")

for review in body["data"]:
    print(f"{review['score']}⭐  {review['title']}")
    print(f"  {review['text'][:100]}...")

Bulk Fetch — All Reviews in One Call

Use maxItems=500 to get up to 500 reviews in a single request. Pullbay paginates Apple's feed internally and returns everything at once:

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://api.pullbay.com/appstore/reviews",
    params={
        "appId":    "284882215",
        "country":  "us",
        "maxItems": 500,
    },
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=120,   # Allow time for internal pagination
)

body = response.json()
print(f"Total reviews: {len(body['data'])}")
print(f"Credits charged: {body['pricing']['creditsCharged']}")
print(f"requestId: {body['requestId']}")

Page-by-Page Iteration

Use page when you want to process reviews incrementally or stop early:

import requests

API_KEY = "YOUR_API_KEY"
all_reviews = []

for page in range(1, 11):   # Apple's feed caps at 10 pages
    response = requests.get(
    "https://api.pullbay.com/appstore/reviews",
        params={"appId": "284882215", "country": "us", "page": page},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=30,
    )
    body = response.json()
    all_reviews.extend(body["data"])

    if not body["pagination"]["hasNextPage"]:
        break

print(f"Collected {len(all_reviews)} reviews")

---

Understanding the API Response

Every Pullbay response follows the same envelope:

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "id": "13997548250",
      "date": "2026-04-25T19:57:33-07:00",
      "userName": "JohnDoe123",
      "userUrl": "https://itunes.apple.com/us/reviews/id1632846422",
      "score": 5,
      "title": "Best app for staying connected",
      "text": "Love the new features in the latest update!",
      "version": "10.2.1",
      "url": "https://itunes.apple.com/us/review?id=284882215&type=Purple%20Software",
      "country": "US"
    }
  ],
  "pagination": {
    "page": 1,
    "hasNextPage": true,
    "cursor": null,
    "offset": null
  },
  "pricing": {
    "creditsCharged": 52
  }
}

Top-Level Fields

Field	Description
requestId	Unique request identifier — log this for every call; it is the key piece of information when contacting support
success	true on success, false on error
data	Array of review objects
pagination	Page state — only meaningful when using page mode; fields are null in bulk (maxItems) mode
pricing.creditsCharged	Credits consumed by this request

Review Object Fields

Field	Type	Description
id	string	Unique review identifier — use as primary key for deduplication
score	integer 1–5	Star rating
title	string	Review headline
text	string	Full review body
userName	string	Reviewer's App Store display name
userUrl	string	Link to reviewer's profile
date	string	ISO 8601 datetime when the review was posted
version	string	App version the reviewer had installed
url	string	Direct link to the review (for developer reply)
country	string	2-letter country code of the storefront

Pagination Fields

pagination is only meaningful in page mode. In maxItems (bulk) mode, all fields are null.

Field	Description
hasNextPage	true if more pages exist — use to control your iteration loop
page	The page number returned

Error Responses

{
  "requestId": "3b8dcb68-1f8c-4a7b-b9e7-63a7b9986f24",
  "status": 400,
  "message": "Validation failed",
  "success": false,
  "error": { "code": "VALIDATION_ERROR" }
}

HTTP Status	Error Code	Cause
400	VALIDATION_ERROR	Invalid parameter name or value
401	AUTHENTICATION_UNAUTHORIZED	Invalid or missing API key
402	TEAM_INSUFFICIENT_CREDITS	Credit balance is 0
429	RATE_LIMIT_EXCEEDED	Request rate exceeded for your plan
5xx	—	Server-side error; retry with backoff

---

Rate Limits

Rate limits are enforced per API key on a per-second and per-minute basis. Exact limits depend on your plan — check the dashboard under Account → Plan. Credits are charged per review returned, not per request.

Failed requests (any non-2xx response) do not consume credits.

---

Frequently Asked Questions

Does Pullbay require App Store credentials?

No. You don't need an Apple Developer account or App Store credentials. Provide the public app ID (visible in the App Store URL) or bundle ID, and Pullbay handles the rest.

How fresh is the review data?

Data is fetched from Apple's review feed on demand when you make a request. Apple's feed has a natural lag of 1–24 hours from when a review is published to when it appears. This is an Apple limitation, not a Pullbay limitation. For monitoring, polling every 1–6 hours is sufficient for most use cases.

Can I get reviews for any country?

Yes. Use the country parameter with a 2-letter ISO 3166-1 alpha-2 code (e.g. us, gb, jp). The App Store has regional review feeds; Pullbay supports all active storefronts.

Can I filter reviews by date or rating?

No — the endpoint does not support since, until, or rating filter parameters. Fetch reviews and apply filters in your own code:

# Filter to last 7 days
from datetime import datetime, timezone
cutoff  = datetime.now(timezone.utc).timestamp() - 7 * 86400
recent  = [r for r in body["data"] if datetime.fromisoformat(r["date"]).timestamp() > cutoff]

# Filter to low scores
low = [r for r in body["data"] if r["score"] <= 2]

What is the maximum number of reviews I can fetch?

Apple's review feed is limited to 10 pages of ~50 reviews each — a maximum of 500 reviews per app per country storefront. Use maxItems=500 to receive all of them in a single response.

What happens if a request fails?

Failed requests don't consume credits — you are only charged for successful 2xx responses. If you receive a 5xx error, retry with exponential backoff.

Can I use `bundleId` instead of `appId`?

Yes. bundleId (e.g. com.atebits.Tweetie2) is a valid alternative identifier. Pass exactly one of appId or bundleId — not both.

---

Next Steps

1. Get your API key — sign up at pullbay.com and create a key from the dashboard

2. Run your first request — copy the cURL example above and replace YOUR_API_KEY with your actual key

3. Set up monitoring — see the Review Monitoring Guide for scheduling patterns, alerting, and database storage

4. Build integrations — see the n8n, Google Sheets, and Backend Integration guides for workflow examples

For questions or to report issues, contact [email protected] and include the requestId from the error response.

---

Key Takeaways

• The endpoint is GET https://api.pullbay.com/appstore/reviews

• Use appId (numeric) or bundleId (reverse-domain) — exactly one, never both

• Use maxItems=1–500 for a bulk single-call fetch; use page=1–10 to iterate page by page — never both in the same request

• Sort options are recent (default) and helpful only

• Review fields: score (not rating), text (not content), userName (not author)

• Credits are reported in pricing.creditsCharged — log it alongside requestId for every call

• Check pagination.hasNextPage (not has_more) when paginating

• Failed requests do not consume credits

• Maximum 500 reviews per app per country (Apple's feed limit)