Docs
Ctrl+K Search Alt+[Alt+] Guides
Get API key

API · Ad library

Magic AI API (/api/v1/magic-ai)

This page documents the programmatic Magic AI endpoint. Use it with an API key to run the same competitor-discovery flow used by the dashboard.

Endpoint

  • Method: POST
  • Path: /api/v1/magic-ai
  • Auth: X-API-Key or Authorization: Bearer <key>
  • Content type: form payload (application/x-www-form-urlencoded or multipart/form-data)

Use /api/v1/magic-ai for API-key integrations.
/api/magic-ai is the dashboard session route used by the web app.

Minimum request body

Send at least one search input:

  • text (free-text prompt), or
  • image (uploaded file), or
  • image_url (public image URL)

Recommended pagination fields:

  • page (start with 0, increment on each continuation)
  • scroll (empty on first request; then send the scroll returned by the previous response)
  • limit (optional page size; default 20, max 50 on first request; stored in scroll for continuations)

API pagination: scroll is an opaque server token (1 hour TTL). Repeat the same search inputs and filters on each continuation request. No browser cookies are required.

Optional filters

You can pass the same filters used in the Magic AI UI:

  • countries - comma-separated country codes or All
  • from, to - start-date range
  • fromlastseen, tolastseen - last-seen date range
  • activefilter=active - restricts results to ads last seen within the past 4 days
  • minadspend, maxadspend - ad spend range
  • mindays, maxdays - days-running range
  • adscorefilter - ad score preset

If a filter is omitted, default behavior follows the product defaults.

Example: text search

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34" \
  --data-urlencode "countries=US" \
  --data-urlencode "page=0" \
  --data-urlencode "scroll="

Example: continue pagination

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34" \
  --data-urlencode "countries=US" \
  --data-urlencode "page=1" \
  --data-urlencode "scroll=<scroll_token_from_previous_response>"

Response shape

Typical success response:

{
  "data": [
    {
      "id": "...",
      "ad_creative_body": "...",
      "ad_snapshot_url": "...",
      "image_url": "...",
      "country": "US"
    }
  ],
  "scroll": "..."
}
  • data is an array of matched ads.
  • scroll is the cursor for the next page. If no more data exists, it can be empty or null.

Each page returns up to 20 ads.

Errors and limits

This endpoint follows the same API-key auth and metering rules as the rest of the Standard API surface:

  • 401 invalid/missing API key
  • 403 account does not include API access
  • 429 rate limit or monthly credits exhausted

See: