One envelope across every platform
TikTok, Instagram, YouTube, LinkedIn, and the rest of the 17-platform catalog share the same top-level shape: data for the payload, meta for requestId, creditsCharged, and version. 137 marketplace operations, one parser habit.
The envelope is the contract
Successful responses wrap the platform payload in { data, meta }. Errors use a typed { error } shape. You branch on HTTP status and outcome fields — not on whether this publisher returned an empty array, a 404 page, or a stringified null.
meta.requestId is for logs and support. meta.creditsCharged is what the call cost. meta.version tracks the API surface. Platform-specific fields live under data, with lookupStatus (where the route documents it) telling you found vs not_found before you write to a warehouse.
Unified does not mean identical payloads
A TikTok profile and a LinkedIn company page do not share every nested field. Unified means the wrapper and the operational metadata stay stable, and common concepts (handles, metrics, media URLs) use consistent naming where the domain overlaps.
List routes that omit lookupStatus document that in OpenAPI — often you call a profile GET first when you need an explicit private / not_found outcome. The capability matrix and error docs spell those cases out.
Why teams care
One retry policy
Retry 503s. Do not retry a completed not_found. Same decision tree for Instagram and Reddit.
One support workflow
Every ticket starts with requestId. We do not ask which marketplace listing you bought.
SDK and OpenAPI stay aligned
The TypeScript SDK is generated from the same OpenAPI that powers docs and the playground.
Agents get the same shape
MCP tools and REST return the same envelope. Pin typed tools once Ask shows you the route.
How to integrate once
- 1
Parse the envelope
Check HTTP status, then data.lookupStatus (when present), then the payload. Log meta.requestId on every response.
- 2
Map fields per resource type
Profile cards, posts, and transcripts still differ by platform — but your meta and error handlers do not fork.
- 3
Follow versioned docs
When a field changes meaning, we document it. Prefer OpenAPI schemas over scraping HTML examples from a blog post.
Read the contract
- Errors
Success vs error envelopes, lookupStatus, retry rules.
- API reference
Per-operation schemas generated from OpenAPI.
- Capability matrix
Outcomes and pagination notes per route.
- Quickstart
Auth header and first live request.
FAQ
What is the Social Fetch unified schema?
Every marketplace success response uses { data, meta }. meta carries requestId, creditsCharged on metered routes, and version. data holds the platform payload and, where documented, lookupStatus.
Are all platform fields the same?
No. Nested payloads differ by resource. The envelope and operational fields stay consistent so logging, billing, and support do not fork per network.
How do errors look?
Failures use a typed error envelope with machine-readable codes. See the Errors docs. Do not assume every vendor returns JSON on failure — we do.
Does Ask use the same schema?
Yes. POST /v1/ask returns the same top-level envelope, plus data.routedOperation for the nested lookup.
Does this cover all 17 platforms?
Yes. The 137 marketplace operations across 17 platforms share the envelope. Auth and system routes follow the same documentation conventions.
Where is the OpenAPI spec?
Download /openapi.json from the site, or browse operation pages under /docs/api. The TypeScript SDK tracks that spec.
See the envelope on a live call
100 free credits. Hit any profile route and inspect data + meta in the response.