> ## Documentation Index > Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # App Store reviews > Canonical Apple storefront reviews with app identity, rating, full text, reviewer and UTC publish date. Reads native 50-row pages without dropping the first review. Depth defaults to 50, rounds upward by 50 and clamps at 500. Country accepts an Apple ISO storefront, UK alias, or a name/numeric location code from the published metadata. Most-recent and most-helpful orders are native. Date windows retain undated reviews; since stops at older rows and requires recent order. Nonempty uncached results cost 5 credits independent of depth; confirmed empty lists/windows, errors, cache and successful replays are free. Original reviewer language is not translated or filtered. Enrichment and fit remain unavailable; default judgments explicitly report skipped, and label=none or judgments=off omits that block. Native public source is rate-limited to 20 reads/minute; no upstream availability guarantee. Read original Apple storefront reviews on the canonical `{ review }` shape. Every row includes its ID, `entity_id`, stars, title, full text, reviewer and UTC publication time when supplied. The first feed entry is preserved. Unknown language, helpful votes, purchase verification, images and developer responses remain null. `depth` defaults to 50, rounds upward to a 50-review page, and clamps at **500**. A request for 51 reads up to 100; 501 reads at most 500. This is Apple's finite recent/helpful feed, not lifetime review history. `total` counts returned rows. `pagination` reports pages and source rows scanned, effective depth and why the walk stopped. There is no continuation cursor beyond that bounded collection. Choose `most_recent` (default) or `most_helpful`. `since` and `until` require recent ordering; date-only upper bounds include the entire UTC day. Older rows stop a `since` walk; newer rows excluded by `until` do not stop it. Undated rows are retained. Supported aliases include `published_after`, `start_date`, `from_date`, `published_before`, `end_date`, `to_date`, `publish_time` and `max_age_days`. Country selects the actual feed: an Apple storefront ISO code, `UK`, or a country name/numeric code from the current location metadata, such as `United Kingdom` or `2840`. `language` records your requested locale; Apple reviewer text remains original, without translation or language filtering. A nonempty uncached collection costs **5 credits**, regardless of depth. Set `X-Max-Credits: 5`. Confirmed empty feeds/windows and all failures are free; successful replay and cache hits are also free. Repeated IDs, wrong app/country, malformed rows, ignored ordering or a failed later page reject the entire collection without charging for partial data. Native source calls share a 20-read/minute budget. `rating` returns free 400 because Apple cannot filter stars upstream. Judgment enrichment and `fit` remain unavailable. Default/on judgments report `status: skipped`, zero pending jobs and `review_judgments_unavailable`; `label=none` or `judgments=off` removes that block. Explicit unsupported labels/fit options return free 422. This endpoint does not infer sentiment from stars. ## OpenAPI ````yaml GET /app_store/app-reviews openapi: 3.1.0 info: title: SocialQuery API version: '2026-10-09' description: >- Documented requests for public-source records. Inspect accepted inputs and credit amounts, then verify the selected operation before integrating preview coverage. servers: - url: https://socialquery.dev/v1 security: - apiKey: [] paths: /app_store/app-reviews: get: tags: - App Store summary: App Store App Reviews description: >- Canonical Apple storefront reviews with app identity, rating, full text, reviewer and UTC publish date. Reads native 50-row pages without dropping the first review. Depth defaults to 50, rounds upward by 50 and clamps at 500. Country accepts an Apple ISO storefront, UK alias, or a name/numeric location code from the published metadata. Most-recent and most-helpful orders are native. Date windows retain undated reviews; since stops at older rows and requires recent order. Nonempty uncached results cost 5 credits independent of depth; confirmed empty lists/windows, errors, cache and successful replays are free. Original reviewer language is not translated or filtered. Enrichment and fit remain unavailable; default judgments explicitly report skipped, and label=none or judgments=off omits that block. Native public source is rate-limited to 20 reads/minute; no upstream availability guarantee. operationId: get_app_store_app_reviews parameters: - name: app_id in: query required: true example: '324684580' schema: type: string description: One numeric Apple App Store app ID. - name: country in: query required: false schema: type: string description: >- Apple storefront ISO code, UK alias, or a country name/numeric code in the metadata directory. Examples: US, United Kingdom, 2840. Default US. - name: language in: query required: false schema: type: string description: >- Records the requested locale. Native reviews remain in their original text; this does not translate or filter review language. - name: depth in: query required: false example: 50 schema: type: integer description: >- Positive requested depth. Defaults to 50, rounds up to a 50-row page and clamps to 500. Date filtering can return fewer rows. - name: sort_by in: query required: false example: most_recent schema: type: string enum: - most_recent - most_helpful - name: rating in: query required: false schema: type: integer description: >- Unsupported by the native feed. Returns free 400; filter review.rating.value locally. - name: label in: query required: false schema: type: string description: Only none is supported. Other labels return free 422. - name: reports in: query required: false schema: type: string description: >- Not implemented by this adapter; returns free 422 before source calls. - name: judgments in: query required: false schema: type: string enum: - 'on' - 'off' description: >- Default/on reports skipped with review_judgments_unavailable. Off omits labels. No background judgment jobs are queued. - name: dry_run in: query required: false schema: type: string enum: - '1' - name: label_evidence in: query required: false schema: type: string enum: - '1' description: >- Not implemented by this adapter; returns free 422 before source calls. - name: fit in: query required: false schema: type: string enum: - goal description: >- Not implemented by this adapter; returns free 422 before source calls. - name: goal in: query required: false schema: type: string description: >- Not implemented by this adapter; returns free 422 before source calls. - name: fit_tokens in: query required: false schema: type: integer description: >- Not implemented by this adapter; returns free 422 before source calls. - name: since in: query required: false schema: type: string description: >- Inclusive ISO timestamp or UTC calendar date. Requires most_recent; older rows stop the walk. Undated rows are kept. - name: until in: query required: false schema: type: string description: >- Inclusive upper timestamp or whole UTC calendar day. Requires most_recent; newer rows are skipped while the walk continues. - name: Cache-Control in: header required: false example: no-cache schema: type: string - name: Idempotency-Key in: header required: false example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c schema: type: string - name: X-Max-Credits in: header required: false description: >- Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero. schema: type: integer minimum: 0 - name: published_after in: query required: false description: >- Alias for since. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: start_date in: query required: false description: >- Alias for since. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: from_date in: query required: false description: >- Alias for since. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: published_before in: query required: false description: >- Alias for until. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: end_date in: query required: false description: >- Alias for until. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: to_date in: query required: false description: >- Alias for until. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: publish_time in: query required: false description: >- Alias for relative lower bound (yesterday, this-week, this-month, last-3-months, last-6-months). Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string - name: max_age_days in: query required: false description: >- Alias for relative lower bound, 0–36500 days. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest. schema: type: string responses: '200': description: >- Canonical Apple storefront reviews with app identity, rating, full text, reviewer and UTC publish date. Reads native 50-row pages without dropping the first review. Depth defaults to 50, rounds upward by 50 and clamps at 500. Country accepts an Apple ISO storefront, UK alias, or a name/numeric location code from the published metadata. Most-recent and most-helpful orders are native. Date windows retain undated reviews; since stops at older rows and requires recent order. Nonempty uncached results cost 5 credits independent of depth; confirmed empty lists/windows, errors, cache and successful replays are free. Original reviewer language is not translated or filtered. Enrichment and fit remain unavailable; default judgments explicitly report skipped, and label=none or judgments=off omits that block. Native public source is rate-limited to 20 reads/minute; no upstream availability guarantee. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: type: object properties: items: type: array maxItems: 500 items: type: object properties: review: type: object properties: id: type: string entity_id: type: string url: type: 'null' title: type: string text: type: string rating: type: object properties: value: type: integer minimum: 1 maximum: 5 max: const: 5 required: - value - max additionalProperties: false author: type: object properties: name: type: string avatar_url: type: 'null' url: type: string format: uri location: type: 'null' reviews_count: type: 'null' required: - name - avatar_url - url - location - reviews_count additionalProperties: false helpful_votes: type: 'null' verified: type: 'null' source: const: app_store language: type: 'null' original_language: type: 'null' translated: const: false images: type: 'null' responses: type: 'null' published_at: type: - string - 'null' ext: type: object properties: version: type: - string - 'null' required: - version additionalProperties: false required: - id - entity_id - url - title - text - rating - author - helpful_votes - verified - source - language - original_language - translated - images - responses - published_at - ext additionalProperties: false required: - review additionalProperties: false total: type: integer minimum: 0 returned_count: type: integer minimum: 0 dropped: const: 0 next_cursor: type: 'null' app_id: type: string country: type: string requested_language: type: string sort_by: type: string enum: - most_recent - most_helpful pagination: type: object properties: pages_fetched: type: integer minimum: 1 maximum: 10 scanned: type: integer minimum: 0 requested_depth: type: integer minimum: 1 effective_depth: type: integer minimum: 50 maximum: 500 stopped_at: type: string enum: - depth - since - exhausted - source_limit required: - pages_fetched - scanned - requested_depth - effective_depth - stopped_at additionalProperties: false source_updated_at: type: - string - 'null' coverage_note: type: string labels: type: object properties: mode: const: default status: const: skipped pending: const: 0 skipped_count: type: integer minimum: 0 required: - mode - status - pending - skipped_count additionalProperties: false _warnings: type: array items: type: string required: - items - total - returned_count - dropped - next_cursor - app_id - country - requested_language - sort_by - pagination - source_updated_at - coverage_note additionalProperties: false required: - data '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '405': $ref: '#/components/responses/Error405' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' '503': $ref: '#/components/responses/Error503' '504': $ref: '#/components/responses/Error504' components: schemas: SocialQueryResponse: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - data properties: success: type: boolean const: true platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean data: type: object additionalProperties: true description: >- The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null. SocialQueryError: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - error properties: success: type: boolean const: false platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean error: type: object required: - code - type - message - status - doc_url properties: code: type: string type: type: string message: type: string status: type: integer doc_url: type: string format: uri responses: Error400: description: Upstream rejected the request. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error401: description: Missing, expired, invalid, or revoked API key. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error402: description: Insufficient SocialQuery credits. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error403: description: Key scope or provider policy denied access. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error404: description: Endpoint or upstream resource not found. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error405: description: HTTP method is not supported. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error409: description: Idempotency conflict or request in progress. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error422: description: Invalid parameters. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error429: description: Request limit reached. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error500: description: Request processing failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error502: description: Upstream service failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error503: description: Provider or required service is unavailable. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error504: description: Upstream service timed out. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.