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 itsdatais theConventionsDataschema: an object with snake_case keys and any JSON values. profile/fullon TikTok, LinkedIn, X and YouTube is beta with typed parts:data.profileis a profile anddata.posts[].postare posts. Only its other keys follow this page. See Response schema.
Example
/v1/hackernews/search?query=Dropbox, shortened:
{
"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. nullfor a field it lacks. A field can be absent rather thannull. 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.
unavailableis 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
confidenceon/v1/youtube/video/sponsors, for example.
Code against a beta endpoint
- Read the keys you need and nothing else, and treat each one as optional.
- Never parse an id as a number. Parse times from the keys listed above; treat any other date as text.
- 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.
- Keep the raw
datawhen you store results, so you can re-read it if a field moves. - For the four entities, prefer the typed endpoint where one exists. Choosing endpoints lists them per platform.