Rate limits and quotas

Limits by plan#

Three things limit the API: your credit balance, which each successful brand lookup spends one of; a per-minute request limit shared by every endpoint and every key on your account; and a monthly allowance of searches and of logo requests sent with a key.

Prices are on the pricing page. Every account starts with free credits; each successful subscription payment adds the plan's credits, and a top-up pack adds more. Credits never expire: what a month does not use rolls over, through plan changes and after a cancellation.

Monthly limits#

Search and the logo CDN never spend a credit. Instead, each plan includes a number of each per calendar month (UTC), counted across every key on your account. The count starts over at midnight UTC on the 1st, and an upgrade raises the allowance at once.

• Searches count once each when they answer 200, from a secret or a publishable key, on /v1/search, /v2/search and the MCP server's search_brands. Past the allowance, search answers 429 with quota_exceeded and a Retry-After that runs to the 1st.
• Logo renders count logo CDN requests sent with one of your keys. Requests without a key never count, and neither do the ones our CDN's cache answers. Past the allowance, logos keep loading: a request with your key is served as if it had none (brands already indexed, at the per-visitor limits) and says so in an X-Api-Key-Status: quota-exceeded header.
• GET /v1/me returns this month's counts and your plan's allowances, and the usage page in the dashboard shows them.

What costs a credit#

• A Brand API request that returns a brand, on /v1 or the /v2 alias.
• Each brand found by a batch request. Duplicate domains in one batch count once.
• A get_brand call through the MCP server that finds a brand.

Nothing else costs a credit: lookups that fail or find nothing, search, /v1/me, the logo CDN and asset URLs. A failed lookup's credit is handed back the moment it fails. Search and logo requests with a key count toward the monthly limits instead.

Headers#

All of them are readable from browser code: the API lists them in Access-Control-Expose-Headers.

At the limit#

Over the per-minute limit, requests answer 429 with the code rate_limited and a Retry-After header: wait and retry. With no credits left, brand lookups answer 402 with insufficient_credits until credits are added. Do not retry that one on a timer. Past the monthly search allowance, search answers 429 with quota_exceeded, whose Retry-After runs to the 1st (UTC): check the code before you wait on it. There are no overage charges: we stop, we do not bill.

A lookup of a domain we have not indexed yet crawls it live. Besides your plan's crawl limit, the whole service has a ceiling on live crawls per minute. At that ceiling such a lookup answers 503 with a Retry-After header and is not counted; brands already indexed are served as usual.

async function getBrand(domain, attempt = 0) {
  const res = await fetch(`https://brandidentityapi.com/v1/brands/${domain}`, {
    headers: { Authorization: `Bearer ${process.env.BRAND_IDENTITY_API_KEY}` },
  });

  if (res.status === 402) {
    // Out of credits: retrying will not help until someone adds credits.
    const { error } = await res.json();
    throw new Error(`${error.message} (balance ${error.details?.balance})`);
  }

  if (res.status === 429) {
    if (attempt >= 3) throw new Error("Still rate limited after 3 retries");
    const wait = Number(res.headers.get("Retry-After") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    return getBrand(domain, attempt + 1);
  }

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(`${error.code}: ${error.message}`);
  }
  return res.json();
}

Logo CDN limits#

The logo CDN has its own burst limits and never touches your credits:

Only requests that miss our CDN's cache reach these counters, so a page of popular logos rarely comes close. Requests with a key also count toward your plan's monthly logo renders. Past a crawl limit, a domain we have not indexed gets the fallback image until the minute ends.