Brands & Brand tracker

This supplements the API reference. GET /api/v1/brands is the API-key tracked-brands list (metered credits). Detail tabs and deep brand analytics use /api/brands/* in the browser while you are logged in.

Path note: Tracked brands over an API key: only GET /api/v1/brands. GET /api/brands is the dashboard list for the logged-in session (same underlying data, not the metered JSON route for keys). Meta ad library (GET /api/v1/adlibrary) is documented in Meta ad library.

MCP tool (Brand tracker)#

• list_tracked_brands — same data as GET /api/v1/brands (optional search, sort, board_id).

Setup: MCP. Parameters: MCP · tools reference. For search_facebook_ads, see Meta ad library.

Shared auth and metering (/api/v1/adlibrary, /api/v1/brands)#

GET /api/v1/brands uses the same auth and metering path as /api/v1/adlibrary. Full parameter context for the ad library route lives in Meta ad library.

• API key: X-API-Key, Authorization: Bearer, or ?api_key= (see API reference).
• Session: If the visitor is already logged in, the same routes can run without a key; the active user must still meet the API access check below.
• Plan: Account must include API access. Otherwise 403.
• Credits / rate limit: Monthly API credits and 60 requests per minute per user. On exhaustion, 429 with a JSON error and optional credits object.

When you use an API key without an existing browser session, the server still resolves the key to your account for that request so behavior matches the dashboard.

GET /api/v1/brands — Tracked brands list (API key)#

Returns the same tracked-brands list you see in the app’s Brand tracker, scoped to the API key owner.

Query parameters#

Response#

JSON array of brand rows (not wrapped in { success, data }). Each item includes fields such as id (Facebook page id), name, logo_url, added_at, page_url, status, total_ads, active_ads_on_page, formats, new_ads_count, new_ads_change, and related summary fields (same shape as the in-app list).

Brand details (GET /api/brands/*) — session / logged-in#

These routes require a logged-in browser session (except GET /api/brands/shared-board, which uses a token). They are not the metered API-key list — that is GET /api/v1/brands only. Automating detail tabs means driving the app with session cookies, not the API key alone.

Brand identifier: Almost all detail endpoints take id = Facebook page_id (same as id in the brands list).

Track / untrack brands (session)#

Yes — you can both track and remove brands in the Brand tracker, using session-authenticated routes:

Track a brand#

POST /api/brands/follow

JSON body:

{ "url": "https://www.facebook.com/ads/library/?view_all_page_id=108897621643793" }

Notes:

• Requires a logged-in session and plan capacity.
• Returns success, plus brand, has_data, and details_url when accepted.

Remove a tracked brand#

POST /api/brands/unfollow

JSON body:

{ "page_id": "108897621643793" }

Notes:

• Removes the brand from your tracker.
• Also removes that brand from your boards for the current user.
• Returns success, amount, and max_allowed.

Count tracked brands#

GET /api/brands/amount-tracked returns:

• amount - number of brands currently tracked by the logged-in user.
• max_allowed - plan cap for Brand tracker.

Date range filter (many detail tabs)#

Query parameters map as follows:

Used directly by GET /api/brands/ads. The same filter applies to other brand insight tabs (ad copies, headlines, hooks, personas, themes, …): pass the same date_range / date_from / date_to query params on those endpoints.

Example: paginated ads for one brand#

GET /api/brands/ads?id={page_id}&page={n}

• page: 0-based page index (12 ads per page).
• Optional date filter: date_range, date_from, date_to as above.
• Response: JSON array of processed ad objects.

Other detail endpoints — common query parameters#

Brand-related routes are also summarized in the API reference.