Rate Limiting

The Brandsearch API enforces rate limits and quotas to ensure fair usage. This page explains the limits by tier and how to handle them.

Rate limits by tier

Rate limits are applied per API key. Each tier has different limits across multiple time windows.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "details": {
      "retry_after": 12,
      "window": "1m"
    }
  }
}

Quotas

In addition to rate limits, each API key has daily and monthly request quotas.

Quotas reset automatically — daily quotas reset at midnight UTC, and monthly quotas reset on the 1st of each month.

You can fetch live counters at any time with GET /v1/usage, which is unmetered.

Free (unmetered) endpoints

Some endpoints don't count against your quota:

• GET /v1/lookup — resolve a name/domain/handle to a brand ID
• GET /v1/me — your account info
• GET /v1/usage — live quota counters
• GET /v1/facets/* — enumerate valid filter/sort/field values

These responses include X-Quota-Charged: false so you can verify the request was not metered.

Credits (per-row tracking)

In addition to request count, every metered response carries an X-Credits-Used header showing how many rows were charged:

• List endpoints charge 1 credit per returned row (so a page_size=20 response costs up to 20 credits).
• Detail endpoints (GET /v1/meta-ads/{ad_id}, etc.) charge 1 credit.
• Free endpoints above charge 0 credits.

Credits are currently informational — there is no daily or monthly limit on credits yet, but counters (credits_used_today, credits_used_this_month) are exposed via GET /v1/usage.

Response headers

Every API response includes headers showing your current quota usage:

Handling rate limits

When you hit a rate limit, the API returns a 429 status with a Retry-After header. The best practice is to implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options)

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '1')
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000))
      continue
    }

    return response
  }

  throw new Error('Max retries exceeded')
}