InsightSocial APISchema 2
The only response shape since October 4, 2026, and what changed from the previous one.
Since October 4, 2026 every API key gets schema 2, and it is the only shape served: one shape per entity (post, profile, comment, transcript) on every platform, whichever data source answered. The envelope is the same; what changed is inside data. Every response says which schema it follows:
{ "success": true, "schema_version": "2", "data": { ... }, "unavailable": [] }The previous shape is no longer served. An InsightSocial-Version header is ignored, and /v1/openapi-legacy.json is gone.
What changed
| Before | Schema 2 |
|---|---|
computed (engagement rate, language, category, estimated reach, vs_creator) on every item | Removed. |
labels, relevance, label_share, labels_evidence, creator_baseline, comment_recency, dropped, _warnings | Removed. What a response could not fill is listed in unavailable instead. |
data.next_cursor | Removed. Read pagination.next_cursor. |
Cursors is.… / is2.… | Cursors v2c.…. Send them back as cursor, with the same parameters, within 24 hours. |
| Ids sometimes numbers | Always strings. |
| Times as ISO strings or epoch numbers | Always ISO 8601 UTC, ending in Z. |
content.media_urls a string or an array | Always an array. |
Author id in ext.author_id (some platforms) | author.id on every post and comment, null where the source has none. |
Language in ext.content_language / ext.default_language | language on posts and comments. |
ext.followers_approximate | followers_approximate on profiles. |
Bio link in ext.bio_link, or in url on Instagram | external_url. url is always the profile itself. |
ext keys in mixed case (YouTube) | snake_case: madeForKids → made_for_kids. |
A top-level comment's parent_id set to the post id (X, Reddit) | null. Replies carry their parent comment's id. |
Facebook author.username holding an opaque pfbid… id | author.id; username is null. |
Reddit author.display_name holding the t2_… account id | author.id; display_name is null. |
YouTube comment ext.replies_token | Removed. Fetch replies with the comment's id as continuationToken. |
New on posts: kind, the format, one of eight values: text, image, carousel, video, short, live, article or link. It is null when the source does not say and the format cannot be read without guessing. New values may be added; keep a default branch.
Transcripts have one shape everywhere: data.transcript is { "language", "text", "segments": [{ "text", "start_seconds", "duration_seconds" }] }, where it used to be a string on some platforms and a list on others.
Parameters that now return 400
A parameter the endpoint does not have also answers 400 UNSUPPORTED_PARAMETER (it used to be ignored and the call still charged). The ones below asked for analysis that schema 2 does not carry. They answer 400 UNSUPPORTED_PARAMETER, with error.param naming the parameter, and nothing is charged:
label, label_evidence, relevance, relevance_threshold, relevant_to, judgments, fit, goal, fit_tokens, seen, brand, brand_description, offer, exclude (except on /v1/pinterest/trends, where it filters terms), brief, use, moments, format=stationery, q on /v1/tiktok/post/transcript and /v1/youtube/video/transcript (it asked a question about the video), and switch_from on /v1/twitter/search/tweets and /v1/reddit/search/comments. Elsewhere q and switch_from are not refused.
dry_run=1 returns our price quote, charges nothing, and reports charge_reason: "dry_run":
{ "data": { "dry_run": { "credits_min": 50, "credits_max": 150 } } }credits_min is the least one page can cost. credits_max is what the call would hold with those parameters (limit, include and the like), multiplied by max_pages when you send it.
unavailable
A list of the fields this platform normally exposes that this response could not fill, as paths into data, for example "items[].post.author.id". Empty when nothing is missing. Fields a platform never shows (Instagram share counts, Reddit view counts) are not listed: they are null everywhere and described on each platform's page.
Prices
Unchanged: a call is still charged what it used. While a metered call runs, the hold on your balance is lower on 24 endpoints, because the analysis they no longer do cannot be charged, and higher on one, /v1/tiktok/search/users (up to 1,310 credits), whose real maximum is above what it used to hold.
The full schema
The OpenAPI document at /v1/openapi.json types every response.