Responses and the envelope, SocialScrape docs

Every answer, success or failure, is JSON in the same envelope.

Success#

200 OKSample response

1{2  "ok": true,3  "credits_charged": 1,4  "credits_remaining": 4999,5  "cached": false,6  "cached_at": null,7  "request_id": "req_0123456789abcdef01234567",8  "data": { },9  "cursor": null,10  "has_more": null11}

Field	Meaning
`ok`	`true` on success.
`credits_charged`	What this request cost. `0` for a cached repeat, a free call or a failure.
`credits_remaining`	The team's balance after the charge.
`cached`, `cached_at`	Whether the answer came from the cache and when it was first fetched. See Caching.
`request_id`	Unique per request. Also sent as the `x-request-id` response header.
`data`	The result: one object, or a `list` object for list endpoints.
`cursor`, `has_more`	Copies of `data.cursor` and `data.has_more` for list endpoints; `null` for single objects. See Pagination.
`raw`	Only with `raw=true`: the platform's original object.

Failure#

1{2  "ok": false,3  "error": { "code": "not_found", "message": "The platform says this profile does not exist.", "retryable": false },4  "credits_charged": 0,5  "request_id": "req_0123456789abcdef01234567"6}

Branch on error.code and error.retryable, never on the message. All codes are on the Errors page. Failures are always free.

One shape for every platform#

Each kind of thing has one model, shared by all platforms: Profile, Post (videos, reels, tweets and pins are posts with a type), Comment, Song, Album, Collection, Community, Transcript, Ad and a few more. The same names mean the same thing everywhere: id, url, platform, author, text, published_at (ISO 8601), duration_seconds, stats and media. Data models lists every field.

A field the platform does not provide is null. We never invent values, and never use 0 or "" for unknown.
Counts are integers. Times are ISO 8601 with a time zone.
Details with no field of their own are in extra, a flat object per platform.

Parameters every endpoint accepts#

Parameter	What it does
`cursor`	Opaque cursor from the previous page; pass it back unchanged. Also accepted as `continuationToken`, `continuation_token`, `next_max_id`, `max_id`, `max_cursor`, `min_time`, `after`, `page_token`, `pageToken`, `paginationToken`, `next_page_id`, `page`. (List endpoints only.)
`region`	Two-letter country code (ISO 3166-1) for results that vary by country. Also accepted as `country`, `geo`. (Endpoints whose results vary by country only.)
`trim`	Smaller response: drops null fields and `extra`.
`raw`	Also return the platform's original object as `raw`.
`max_age_days`	Serve a cached result fetched within this many days, for 0 credits. ScrapeCreators' `cache_max_age=7d` spelling is accepted too. Also accepted as `cache_max_age`.

trim=true removes every null field and extra. raw=true adds the platform's original object next to data; trim and raw do not change the price or the cache entry.

Headers#

Header	Meaning
`x-request-id`	The request id, also in the body.
`retry-after`	On `429` and `503`: seconds to wait before retrying; see Rate limits.
`x-ignored-params`	Names of query parameters the endpoint does not use. Unknown parameters are ignored, not rejected.
`x-idempotent-replay`	`true` when an `Idempotency-Key` returned the first answer again; see Batch and jobs.

Versioning#

Every path starts with /v1. When a platform changes in a way that breaks a response, the one endpoint affected ships a new version and the old one keeps running until it is retired with notice in the changelog. Adding a field to a response is not a breaking change, so ignore fields you do not know.

Every endpoint page is for a built endpoint that a canary watches. Endpoints not built yet are not listed.