Usage, limits & billing

​

What counts as a row

• Mention / appearance rows returned in a list: one row each. The first 5 rows of each distinct pull are free, and repeating the exact same request within 7 days is not re-billed.
• Related-entity rows on aggregated views: one row each, same 5-row allowance.
• Commercial rows (/v1/recommendations, /v1/channels/{id}/sponsors, details=full enrichment items): 10 rows each, because the commercial pipeline is more expensive to run and curate. No free allowance.
• Transcripts: 75 rows per 15-minute block of video, minimum one block, unlock permanent per account. See Transcripts.
• Free: /v1/me, /v1/health, /v1/openapi.json, search, lookup, discovery search (including its recommendations_summary), recommendations_summary aggregate blocks, teasers, and all Community Review submissions and corrections.

​

Checking usage

curl https://api.arcmira.com/v1/me \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

{
  "user_id": "usr_...",
  "tier": "pro_plus",
  "scopes": ["read", "recommendations:read"],
  "rate_limit": 240,
  "recommendations_api_enabled": true,
  "usage": {
    "rows_used": 1234,
    "rows_remaining": 98766,
    "monthly_rows": 100000,
    "current_spend_cents": 0
  }
}

​

Exceeding your monthly allotment

​

Rate limits

​

Backoff pattern

async function callWithBackoff(url: string, init: RequestInit, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, init);
    if (res.status !== 429 || attempt >= maxRetries) return res;
    const retry = Number(res.headers.get('Retry-After') ?? '1');
    await new Promise((r) => setTimeout(r, retry * 1000));
  }
}

import asyncio, httpx

async def call_with_backoff(client, method, url, max_retries=5, **kw):
    for attempt in range(max_retries + 1):
        r = await client.request(method, url, **kw)
        if r.status_code != 429 or attempt == max_retries:
            return r
        await asyncio.sleep(int(r.headers.get('retry-after', '1')))

​

Per-key tracking

​

Reducing costs

• Cache resolved ent_* IDs; don’t re-run lookups.
• Pass entity_id instead of entity_name so no resolution rides inside metered requests.
• Scope pulls with date_from / date_to.
• Pull larger pages (up to limit=100) when iterating: rows cost the same, the request count drops.
• Quote transcripts before unlocking (meta.quote is free) and check usage.rows_remaining first.