Skip to main content

​
Using with AI

Drop one of these into any AI tool or agent alongside your API key:
The first is a summary, the second is the full docs. Works with Claude, ChatGPT, Gemini, and anything else with web access.

​
Authentication

All endpoints require an API key passed in the x-api-key header.

​
Rate limits

Each request costs 1 credit, except Get usage and changes that change nothing (saving something already saved, adding it to a board it’s already on, creating a board you already have, following a brand you already follow, or adding one to a group it’s already in), which are free. Every endpoint’s page shows what it costs. Requests turned away by the rate limit, or for a missing or invalid key, don’t use a credit; one that fails after your key is accepted, such as a 404, does (except changes, which only use a credit when they change something). Exceeding either limit returns a 429 response:
  • Rate limit: the Retry-After header says how many seconds to wait. Every response also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers.
  • Quota: your quota resets at the start of each billing period. The resets_at field in the 429 response tells you exactly when.
A key whose account has no active subscription gets a 403. Changes have their own limits on top of these, per person and shared across all their keys and MCP connections: Going over returns a 429 with a Retry-After header. Changes only cost a credit when they change something: anything already there (a saved creative, a creative on a board, a board with that name, a followed brand, a brand in a group) is free.

​
Searching inside ads

Get creatives and Get brand creatives take a q parameter that searches inside the creatives: their ad copy, video transcripts, on-screen text and landing page URLs. It matches the exact phrase and works alongside every other filter.
Use search_in to look in just one of copy, transcript, on_screen_text or landing_page. Results keep the order_by order rather than being ranked by relevance. To find the brands selling a product or in a niche, search their ads this way: each creative includes its brand_id and brand_name. Search brands only matches brand names and domains. To find a style of ad rather than words in it, such as talking-head videos, unboxings or memes, use visual_format instead. It takes one of the formats in the app’s Visual format filter, and works on every creative feed.

​
Dates

start_date and end_date both filter on when a creative was first seen, so together they are the window the creatives started running in. A bare date covers the whole day, and times without an offset are UTC. To find creatives that have stopped running, use is_active=false.

​
Workspaces

Your followed brands, groups and boards each belong to a workspace, such as one per client. Get workspaces lists yours. Anything not in one of those is in your default workspace, which shows up as workspace_id: null. Get followed brands, Get groups and Get user boards cover all your workspaces unless you pass workspace_id; pass workspace_id=default for the default workspace. To see what the brands are running, Get followed brands’ creatives and Get group creatives return them as one feed, with the same filters as Get creatives.
Workspaces used to be called spaces. /v1/spaces and the space_id parameter on boards still work, but use the workspace names for anything new.

​
Pagination

Paginated endpoints use cursor-based pagination. Creative endpoints return 12 creatives per page. When more results are available, the response includes a next_cursor value. Pass it as the cursor query parameter to fetch the next page.
Send the same order_by, q and filters with a cursor as with the request that returned it. A cursor used with a different order_by returns 400.

​
Errors

All errors return a consistent JSON shape: