> **For coding agents and LLMs:** This is one Social Fetch marketing page (markdown export). For API orientation start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for auth and crawl rules use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for every operation use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt). ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** --- # What is a unified schema? A unified schema means every successful response shares the same top-level shape — one parser instead of one per platform. On Social Fetch that's { data, meta }: logging, billing, and retries don't fork per network. Nested payloads still differ by resource. ## The envelope data holds the platform payload. meta carries requestId, creditsCharged on metered routes, and version — same three keys for TikTok or Spotify. Errors use a typed code plus meta.requestId. Branch on HTTP status and documented fields, not null vs [] guessing. ## A concrete example Instagram and GitHub profile lookups both return top-level data and meta with the same meta keys. Inside data, shapes diverge — Instagram has follower counts; GitHub has repo counts. A missing Instagram handle: HTTP 200, data.lookupStatus not_found. A malformed request: typed error envelope, not an empty 200. ## Unified does not mean identical fields A TikTok video and LinkedIn company page don't share every nested key. Unified means stable wrapper and ops metadata; overlapping concepts use consistent names (follower counts, timestamps). Where documented, read lookupStatus before writing warehouse rows — part of the contract on any route that supports it. ## How teams use it in practice Without a shared envelope, each new platform forks logging, billing, and retry code. With one envelope, adding a platform is mostly a new route under /platforms. Ask, MCP, and typed REST all parse { data, meta } — prototype code carries to production cron jobs with minimal changes. ## How this compares to typical scraper and marketplace APIs Many marketplaces pass each publisher's raw shape through — new platform, new parser. Unified schema normalizes at the API boundary so requestId and billing live in the same place every time. ## Common mistakes and what it is not Treating HTTP 200 as "found it." 200 with lookupStatus not_found is completed and billed — read lookupStatus first. Unified doesn't mean identical fields or invented metrics. Not a caching or rate-limit guarantee. Details: /unified-schema, /docs/errors, /openapi.json. ## FAQ ### What is a unified API schema? Same top-level shape on every endpoint — Social Fetch uses { data, meta } so requestId and creditsCharged always live in the same place. ### Does Social Fetch normalize fields across platforms? Overlapping concepts yes (followers, timestamps). Platform-specific data stays inside data. ### Does Ask use the same schema? Yes — { data, meta } plus data.routedOperation for the nested lookup. ### Where is the OpenAPI spec? /openapi.json and per-operation pages under /docs/api. @socialfetch/sdk follows the same spec. ### Does this cover all 25 platforms? Yes. Marketplace operations across 25 platforms share the envelope. ### Is a 200 response always a successful lookup? No. Check data.lookupStatus — not_found and private are completed, billed answers. ### How is this different from how other scraper APIs structure responses? Many pass through publisher-specific shapes. Unified schema normalizes wrapper and ops fields at the boundary. ## Related - [Unified schema product page](https://www.socialfetch.dev/unified-schema) - [Errors docs](https://www.socialfetch.dev/docs/errors) - [API reference](https://www.socialfetch.dev/docs/api) - [Ask](https://www.socialfetch.dev/ask) - [Request ID](https://www.socialfetch.dev/glossary/request-id) - [Lookup status](https://www.socialfetch.dev/glossary/lookup-status) - [Pricing](https://www.socialfetch.dev/pricing)