InsightSocial APISchema 2
The response shape every key gets from October 4, 2026, what changed from the previous one, and how to keep the old shape until November 3.
From October 4, 2026 every API key gets schema 2: 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": [] }Need the old shape for a while?
Send this header and you get the previous body, unchanged, until November 3, 2026:
curl https://api.insightsocial.app/v1/instagram/profile?handle=nasa \
-H "x-api-key: $INSIGHTSOCIAL_API_KEY" \
-H "InsightSocial-Version: legacy"It works on every key. Those responses carry Deprecation and Sunset headers. After November 3 the header is ignored and every call gets schema 2. Idempotency keys do not carry across: a key used with one schema answers 409 IDEMPOTENCY_KEY_REUSED when reused with the other.
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 (image, carousel, video, short, live, article), null when the source does not say. 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
These 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 the TikTok and YouTube transcript endpoints (it asked a question about the video), and switch_from on X and Reddit search.
dry_run=1 returns our price quote, charges nothing, and reports charge_reason: "dry_run":
{ "data": { "dry_run": { "credits_min": 100, "credits_max": 300 } } }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 2,620 credits), whose real maximum is above what it used to hold.
The full schema
The OpenAPI document at /v1/openapi.json types every response. The previous document stays at /v1/openapi-legacy.json until November 3.