Response envelope
The outer shape every endpoint shares, and how to read it.
Every endpoint returns the same outer object. Writing your integration against this shape once means you can add endpoints later without touching your parsing layer.
{
"request_id": "req_8f2c1d94e7b0",
"success": true,
"status": { "code": "OK", "message": "Scrape completed.", "retryable": false },
"error": null,
"meta": {
"client_id": "client_abc123",
"scraper": "instagram-profile-v4",
"billable": true,
"duration_ms": 4698
},
"data": { }
}The fields
| Field | Type | What it tells you |
|---|---|---|
request_id | string | Identifies this call. Log it. It is the fastest way for us to find a request you are asking about. |
success | boolean | Whether the call produced an answer. Branch on this, not on the HTTP status. |
status.code | string | A stable machine-readable outcome, for example OK or PROFILE_NOT_FOUND. Safe to switch on. |
status.message | string | The same outcome in prose. Written for humans reading logs. Do not parse it. |
status.retryable | boolean | Whether repeating this exact request could produce a different result. |
error | object or null | Present only on failure, carrying the error type. |
meta.scraper | string | Which endpoint answered. Useful when one worker fans out to several. |
meta.billable | boolean | Whether this call counted against your usage. |
meta.duration_ms | integer | How long the call took on our side. |
data | object or null | The result. null on any failure. |
Where the content sits
Most endpoints put their payload directly in data. Some nest it one level
further in data.data, because the endpoint's own response has a data key of
its own.
Rather than reasoning about which is which, read the response example on the endpoint's page. Each one is a real captured response, so the nesting it shows is the nesting you will get.
The standard content shape
Endpoints that return posts use a common inner shape, so the same parsing code works across platforms.
{
"main": { },
"additional": { }
}main holds the fields that mean the same thing everywhere: post_id,
post_url, caption, hashtags, creator_handle, view_count, like_count,
comment_count, share_count, save_count, upload_timestamp,
thumbnail_url, video_url.
additional holds whatever is specific to that platform and has no equivalent
elsewhere. Treat it as a place to look for detail, not as a stable contract
across platforms.
Newer endpoints return the platform's own field names instead, which suits integrations that already speak that platform. The endpoint page tells you which shape you are getting.