System

Endpoints for inspecting the API itself rather than its data — currently a single freshness probe so you can tell how up to date the data is.

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.

Brand, ad and post data is updated continuously: newly collected brands and ads show up in results within minutes. In normal operation lag_hours stays close to zero.

Useful for:

Monitoring — alert when lag_hours climbs above a threshold
Cron clients — hold off on a batch job while the data looks stale
Dashboards — surface "data is N hours old" to your end users

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": 0.04
}