System

Endpoints for inspecting the API itself rather than its data — currently a single freshness probe so you can tell when the latest snapshot landed.

GET/v1/system/freshness

Data freshness

Returns the latest row timestamp per resource (brands, Meta ads, TikTok posts, Instagram posts), the row count for each, the overall freshest signal, and how many hours have passed since.

Useful for:

Cron clients — short-circuit your batch job if today's data hasn't landed yet
Dashboards — surface "data is N hours old" to your end users
Monitoring — alert when lag_hours crosses a threshold

Unmetered. Always returns X-Quota-Charged: false.

Response

Name
brands
Type
object
Description
{latest_at, doc_count} — most recent created_at across all brands and the total brand count.
Name
meta_ads
Type
object
Description
{latest_at, doc_count} for Meta ads (using created_at).
Name
tiktok_ads
Type
object
Description
{latest_at, doc_count} for TikTok posts (using create_time).
Name
instagram_posts
Type
object
Description
{latest_at, doc_count} for Instagram posts (using taken_at).
Name
overall_latest_ready_at
Type
timestamp
Description
The most recent timestamp across all four resources.
Name
lag_hours
Type
number
Description
Hours since overall_latest_ready_at, rounded to two decimals. null if no signal is available.

Request

GET

/v1/system/freshness

curl https://api.brandsearch.co/v1/system/freshness \
  -H "X-API-Key: bsk_your_api_key"

Response

{
  "brands": {
    "latest_at": "2026-04-30T03:14:22+00:00",
    "doc_count": 1284230
  },
  "meta_ads": {
    "latest_at": "2026-04-30T05:42:11+00:00",
    "doc_count": 28412940
  },
  "tiktok_ads": {
    "latest_at": "2026-04-30T04:18:00+00:00",
    "doc_count": 4218300
  },
  "instagram_posts": {
    "latest_at": "2026-04-30T05:01:33+00:00",
    "doc_count": 7112480
  },
  "overall_latest_ready_at": "2026-04-30T05:42:11+00:00",
  "lag_hours": 1.31
}