Skip to content
Benchmark

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. A profile is a public publishing account or channel.

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

Profiles have a Basic view. Posts and links have Basic and Enriched views.

BasicEnriched
ContainsCore identity, text, state, and metricsEverything in Basic, plus the post structure and an analysis, where supported
Available forProfiles, posts, and linksPosts and links
Use it forNormal reads and current source dataUnderstanding how supported content works

A refresh requests the latest available public source state for the selected view. It is not a third view.

Read a stored result first when you can. A refresh performs a new source update, so it costs more.

  • Posts get one Enriched analysis. After a post has a completed analysis, another Enriched refresh returns 409 CONFLICT and 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 outdated notice.

Public analysis sits under the post, post item, media item, or link that it describes. Customer responses contain only the structured fields shown in this schema. They do not include source media or transcript content.

Analysis hierarchy

Post analysis follows the same structure as post data:

  • analysis has facts about the whole post, plus reusable templates.
  • items[].analysis has facts about one carousel slide, thread entry, quote, or root item.
  • items[].media[].analysis has 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 reports whether Benchmark filled the supported fields for this result.

StatusMeaningReasons
completeAll supported fields available for this request were returned.None
partialSome supported fields were unavailable.age_restricted, transcript_unavailable
unavailableNo public result was available.private, not_found

For private, the source indicates that the content is not public. Benchmark does not retrieve it.

Stored reads return complete or partial coverage.

Collections

A refresh starts a research job. The API calls this job a collection. It runs in the background. Poll it until its status is one of these:

  • complete: The job ended. The poll returns the result one time. If no public result was available, it returns result: null with coverage.
  • failed: Benchmark could not produce the requested result. Check its error.

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.

A history refresh accepts maxPosts (default 50, maximum 1,000). There is no date cutoff input. Pinned posts count toward the limit. YouTube history includes videos and Shorts together.