AdnovaDocs
Following Brands

Following Brands overview

Competitor monitoring — tracked brands, per-brand analyses, and brand ads.

The Following Brands API is Adnova's competitor-monitoring surface: the brands a workspace tracks, the analyses Following Brands generates per brand, and the ads held for each tracked brand.

What you can do

  • List tracked brands — every brand the workspace tracks, with aggregate ad stats and a hasAIReport flag.
  • Get a brand analysis — one analysis at a time, selected by dataType + datePreset. The data field takes one of four shapes — see Analysis Types.
  • List a brand's ads — the ads Following Brands holds for a brand, with filters, search, sort, and pagination.

Typical flow

  1. List tracked brands. List tracked brands returns each brand's brandId and a hasAIReport flag.
  2. Pull analyses. Get a brand analysis per dataType — status is ok (analysis fields at the top level) or pending. AI-tier analyses require the brand's hasAIReport: true. The data shape depends on dataType — see Analysis Types.
  3. Browse the brand's ads. List a brand's ads (v2) with filters, per-ad insights, and cursor pagination. The v1 List a brand's ads endpoint (skip/limit) is deprecated but keeps working.

Auth & request context

Every request needs three headers:

api-key: YOUR_KEY_HERE
x-workspace-id: YOUR_WORKSPACE_ID
x-org-id: YOUR_ORG_ID

x-workspace-id and x-org-id are required on every endpoint. The same api-key works across the Adnova APIs; Following Brands API access is provisioned per organization — contact Adnova to enable it.

Credits & pricing

Ad-returning endpoints consume ad credits — 1 credit per ad returned. Your organization has an ad-credit allowance for each billing period that scales with your plan and billing term and resets at the start of every period.

The only metered endpoints here are List a brand's ads (v2) and the deprecated v1 List a brand's ads — each charges 1 credit per ad in the response. Listing tracked brands and brand analyses are free.

Every metered response reports your live balance in headers:

X-Credit-Cost: 25          # credits this request consumed
X-Credits-Remaining: 875   # credits left in the current period
X-Credits-Limit: 1000      # total credits for the current period

When the allowance is exhausted, the endpoint returns 402 with code API_CREDITS_EXHAUSTED and your usage details; credits refresh automatically at the start of the next period.

Check your balance any time with Get API credit usage — it's free and never consumes credits.

Conventions

  • Pagination — opaque nextCursor on the v2 brand-ads listing; skip/limit (offset) on the deprecated v1 listing.
  • Limits — multi-value filter arrays are capped at 10 items; free-text search is capped at 255 characters.
  • Errors — { "error": { "code", "message" } }. See Rate limits and versioning.