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
hasAIReportflag. - Get a brand analysis — one analysis at a time, selected by
dataType+datePreset. Thedatafield 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
- List tracked brands. List tracked brands returns each brand's
brandIdand ahasAIReportflag. - Pull analyses. Get a brand analysis per
dataType—statusisok(analysis fields at the top level) orpending. AI-tier analyses require the brand'shasAIReport: true. Thedatashape depends ondataType— see Analysis Types. - 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_IDx-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 periodWhen 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
nextCursoron 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.
