InsightSocial API
Unified schema

Beta endpoints

What a beta endpoint returns, the naming rules every beta body follows (snake_case keys, string ids, ISO times), and what a beta body does not promise.

Most endpoints are beta: 773 of the 937 data endpoints, including every endpoint on the platforms under "More platforms (beta)" in the sidebar. A beta endpoint does not return one of the schema-2 entities (post, profile, comment, transcript). Its data is the structure the source returns, with our naming rules applied on top. You get the data the same day a source offers it, without waiting for us to map it into an entity, and in exchange the shape is looser and can change.

The other 164 endpoints are typed: their data is a post, profile, comment or transcript, the same on every platform.

How to tell

  • The endpoint's reference page says Beta. under its description, and its platform page marks it Beta.
  • In the OpenAPI document, the operation has "x-stability": "beta" and its data is the ConventionsData schema: an object with snake_case keys and any JSON values.
  • profile/full on TikTok, LinkedIn, X and YouTube is beta with typed parts: data.profile is a profile and data.posts[].post are posts. Only its other keys follow this page. See Response schema.

Example

/v1/hackernews/search?query=Dropbox, shortened:

Response
{
  "success": true,
  "platform": "hackernews",
  "endpoint": "/v1/hackernews/search",
  "schema_version": "2",
  "data": {
    "query": "Dropbox",
    "hits": [
      {
        "id": "8863",
        "type": "story",
        "author": "dhouston",
        "created_at": "2007-04-04T19:16:40.000Z",
        "title": "My YC app: Dropbox - Throw away your USB drive",
        "url": "http://www.getdropbox.com/u/2/screencast.html",
        "score": 104,
        "comment_count": 71,
        "story_id": "8863",
        "parent_id": null,
        "item_url": "https://news.ycombinator.com/item?id=8863"
      }
    ]
  },
  "pagination": { "next_cursor": null, "has_more": false, "page_size": 1 },
  "unavailable": [],
  "credits_used": 20,
  "credits_remaining": 9980,
  "request_id": "req_4c1e9a07b2d3",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": false
}

The rows are in data.hits, not data.items, and a row is not a schema-2 post: it has title and score where a post has content and engagement. Another endpoint names its rows differently.

What every beta body follows

The envelope is the same. success, platform, endpoint, schema_version ("2"), credits_used, credits_remaining, request_id, charge_reason and the rest are on every response, as on Response schema. Errors use the same error body. Prices, free calls, dry_run=1 and Idempotency-Key work as on any other endpoint.

Lists page with cursor. A beta list carries the top-level pagination object. Send pagination.next_cursor back as cursor, unchanged, until has_more is false, as on Pagination. That holds where the source pages by page number too: the page number travels inside our cursor.

Keys are snake_case, at every depth: viewCount arrives as view_count. A key that cannot be written in snake_case is left out.

Ids are strings. A number under a key named id, ids or pk, or ending in _id, _ids or _pk, is sent as a string, so an id above 2^53 survives JSON parsing. An id the source already sends as text stays text.

Times are ISO 8601 in UTC, ending in Z, under every key ending in _at, whether the source sent epoch seconds, epoch milliseconds or a date string we can read. An epoch number under a key ending in date, time or timestamp is converted too, when it is a plausible timestamp (2001 or later); a small number there stays a number, because a watch_time of 120 is a duration.

Missing is null. A value the source wrote as the text undefined, null or NaN, or a number that is not finite, arrives as null.

Our cursors and our prices only. No other provider's name, request id, credit count or cursor is passed on, and bookkeeping a scraper adds about itself (when it scraped, its own warnings) is removed.

What a beta body does not promise

  • A fixed shape. Field names, nesting and which fields are present differ between endpoints, and can change on one endpoint when its source changes, without a new schema version. We list the changes we make in the Changelog; a source can change on its own.
  • One shape across platforms. A Steam app and an App Store app are separate structures. Nothing here is a shared entity you can parse once.
  • Rows under items. A list's rows sit under whatever key the source uses (hits, results, dependents, …), next to other keys about the page.
  • null for a field it lacks. A field can be absent rather than null. Treat every key as optional.
  • Types beyond ids and times. Other values are the source's own: a count can be a number on one endpoint and display text such as "1.2K" on another, and a date that is not under one of the keys above ("2 days ago", a local date) stays as the source wrote it.
  • Field coverage. unavailable is always [] on a beta endpoint. It does not tell you that a field the source usually fills is missing from this response.
  • That every figure is raw data. We remove the scores and labels a source adds on top of the data where we know them, but a figure that is the point of the endpoint stays: the confidence on /v1/youtube/video/sponsors, for example.

Code against a beta endpoint

  1. Read the keys you need and nothing else, and treat each one as optional.
  2. Never parse an id as a number. Parse times from the keys listed above; treat any other date as text.
  3. Check the keys you depend on when you parse a response, and fail loudly (or log) when one is missing, so a change at the source shows up in your logs rather than as empty rows.
  4. Keep the raw data when you store results, so you can re-read it if a field moves.
  5. For the four entities, prefer the typed endpoint where one exists. Choosing endpoints lists them per platform.

Next steps

On this page