Data model
Entities
Benchmark returns one kind of thing at a time. It is called an entity. An
entity is a profile, a post, or a link.
Profiles and posts belong to a platform: instagram, tiktok, youtube, or x.
A link is a web page. It does not belong to a platform.
You point at an entity with a target. A target is a supported URL, a handle, or a platform ID.
Basic and Enriched
Basic and Enriched are two views of the same entity.
| Basic | Enriched | |
|---|---|---|
| Contains | Core identity, text, state, and metrics | Everything in Basic, plus the post structure and an analysis, where supported |
| Use it for | Normal reads and current source data | Understanding how supported content works |
A refresh collects the view you ask for, now. It is not a third view.
Read stored data first when you can. A refresh does new collection work, so it costs more.
- Posts get one Enriched analysis. After a post has a completed analysis, another
Enriched refresh returns
409 CONFLICTand costs no credits. Reads keep returning the existing analysis. - Links are analyzed again when the page changes. Until then, a read can return
the older analysis with an
outdatednotice. - Profiles have no analysis in V1. An Enriched profile holds collected data only.
Public analysis sits under the post, post item, media item, or link that it describes. It never includes stored media, transcript text, prompts, model details, or raw analysis.
Analysis hierarchy
Post analysis follows the same structure as post data:
analysishas facts about the whole post, plus reusable templates.items[].analysishas facts about one carousel slide, thread entry, quote, or root item.items[].media[].analysishas facts about one supported image, video, thumbnail, or other media item.
Link analysis is under analysis. Its analysisFreshness is current when the
analysis matches the current page. It is outdated when the page changed after the
analysis.
Freshness
Every stored response has a freshness value.
current: this is the newest data Benchmark has.stale: Benchmark has newer data than this result.
Coverage
Every result has coverage. Coverage tells you if the data is complete. If it is not complete, coverage tells you why.
| Status | Meaning | Reasons |
|---|---|---|
complete | This is all there is. There are no issues. | None |
partial | You got data, but a part of it could not be collected. | age_restricted, transcript_unavailable |
unavailable | Benchmark could not reach the content. | private, not_found |
Stored reads return complete or partial coverage.
Collections
A refresh returns a collection. A collection is a job that runs in the
background. Poll it until its status is one of these:
complete: the data is ready. The poll returns it one time.failed: Benchmark could not collect the data. Check its coverage for the reason.
The first poll that succeeds returns the data and uses up the collection. Later
polls return 409 COLLECTION_ALREADY_DELIVERED.
Each collection has an expiresAt time, 72 hours after you create it.
A profile-history refresh returns the first ten stored posts. Use the paid stored read to get later pages.