App Store App Reviews

curl --request GET \
  --url https://socialquery.dev/v1/app_store/app-reviews \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/app_store/app-reviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "items": [
      {
        "review": {
          "id": "<string>",
          "entity_id": "<string>",
          "url": null,
          "title": "<string>",
          "text": "<string>",
          "rating": {
            "value": 3,
            "max": 5
          },
          "author": {
            "name": "<string>",
            "avatar_url": null,
            "url": "<string>",
            "location": null,
            "reviews_count": null
          },
          "helpful_votes": null,
          "verified": null,
          "source": "app_store",
          "language": null,
          "original_language": null,
          "translated": false,
          "images": null,
          "responses": null,
          "published_at": "<string>",
          "ext": {
            "version": "<string>"
          }
        }
      }
    ],
    "total": 1,
    "returned_count": 1,
    "dropped": 0,
    "next_cursor": null,
    "app_id": "<string>",
    "country": "<string>",
    "requested_language": "<string>",
    "sort_by": "most_recent",
    "pagination": {
      "pages_fetched": 5,
      "scanned": 1,
      "requested_depth": 2,
      "effective_depth": 275,
      "stopped_at": "depth"
    },
    "source_updated_at": "<string>",
    "coverage_note": "<string>",
    "labels": {
      "mode": "default",
      "status": "skipped",
      "pending": 0,
      "skipped_count": 1
    },
    "_warnings": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

App Store

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.

GET

app_store

app-reviews

App Store App Reviews

curl --request GET \
  --url https://socialquery.dev/v1/app_store/app-reviews \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://socialquery.dev/v1/app_store/app-reviews', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "data": {
    "items": [
      {
        "review": {
          "id": "<string>",
          "entity_id": "<string>",
          "url": null,
          "title": "<string>",
          "text": "<string>",
          "rating": {
            "value": 3,
            "max": 5
          },
          "author": {
            "name": "<string>",
            "avatar_url": null,
            "url": "<string>",
            "location": null,
            "reviews_count": null
          },
          "helpful_votes": null,
          "verified": null,
          "source": "app_store",
          "language": null,
          "original_language": null,
          "translated": false,
          "images": null,
          "responses": null,
          "published_at": "<string>",
          "ext": {
            "version": "<string>"
          }
        }
      }
    ],
    "total": 1,
    "returned_count": 1,
    "dropped": 0,
    "next_cursor": null,
    "app_id": "<string>",
    "country": "<string>",
    "requested_language": "<string>",
    "sort_by": "most_recent",
    "pagination": {
      "pages_fetched": 5,
      "scanned": 1,
      "requested_depth": 2,
      "effective_depth": 275,
      "stopped_at": "depth"
    },
    "source_updated_at": "<string>",
    "coverage_note": "<string>",
    "labels": {
      "mode": "default",
      "status": "skipped",
      "pending": 0,
      "skipped_count": 1
    },
    "_warnings": [
      "<string>"
    ]
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

{
  "success": false,
  "platform": "<string>",
  "endpoint": "<string>",
  "credits_used": 1,
  "credits_remaining": 123,
  "request_id": "<string>",
  "cached": true,
  "error": {
    "code": "<string>",
    "type": "<string>",
    "message": "<string>",
    "status": 123,
    "doc_url": "<string>"
  }
}

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.

Authorizations

x-api-key

string

header

required

Headers

Cache-Control

string

Idempotency-Key

string

X-Max-Credits

integer

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.

Required range: x >= 0

Query Parameters

app_id

string

required

One numeric Apple App Store app ID.

country

string

Apple storefront ISO code, UK alias, or a country name/numeric code in the metadata directory. Examples: US, United Kingdom, 2840. Default US.

language

string

Records the requested locale. Native reviews remain in their original text; this does not translate or filter review language.

depth

integer

Positive requested depth. Defaults to 50, rounds up to a 50-row page and clamps to 500. Date filtering can return fewer rows.

sort_by

enum<string>

Available options:

most_recent,

most_helpful

rating

integer

Unsupported by the native feed. Returns free 400; filter review.rating.value locally.

label

string

Only none is supported. Other labels return free 422.

reports

string

Not implemented by this adapter; returns free 422 before source calls.

judgments

enum<string>

Default/on reports skipped with review_judgments_unavailable. Off omits labels. No background judgment jobs are queued.

Available options:

on,

off

dry_run

enum<string>

Available options:

1

label_evidence

enum<string>

Not implemented by this adapter; returns free 422 before source calls.

Available options:

1

fit

enum<string>

Not implemented by this adapter; returns free 422 before source calls.

Available options:

goal

goal

string

Not implemented by this adapter; returns free 422 before source calls.

fit_tokens

integer

Not implemented by this adapter; returns free 422 before source calls.

since

string

Inclusive ISO timestamp or UTC calendar date. Requires most_recent; older rows stop the walk. Undated rows are kept.

until

string

Inclusive upper timestamp or whole UTC calendar day. Requires most_recent; newer rows are skipped while the walk continues.

published_after

string

Alias for since. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

start_date

string

Alias for since. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

from_date

string

Alias for since. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

published_before

string

Alias for until. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

end_date

string

Alias for until. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

to_date

string

Alias for until. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

publish_time

string

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.

max_age_days

string

Alias for relative lower bound, 0–36500 days. Conflicting absolute aliases are rejected; relative lower bounds combine by taking the latest.

Response

success

boolean

required

platform

string

required

endpoint

string

required

credits_used

integer

required

Required range: x >= 0

credits_remaining

integer | null

required

request_id

string

required

cached

boolean

required

data

object

required

The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null.

Show child attributes