Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt

Use this file to discover all available pages before exploring further.

Arcmira bills premium usage by rows, not by page views or API calls. Rows are the unit of indexed content surfaced to your account — appearance/mention rows, people/organization/topic rows on aggregated views, and so on. API and web usage share the same row pool. A row counted for a web request is not counted again when you also request it via the API. Heavy automation will, however, use rows faster than incidental browsing.

​
What counts as a row

The API records row usage on response based on what you retrieved. As a rule of thumb:
  • Mentions / appearance rows returned in a list each cost one row.
  • Related-entity rows on aggregated views (people, topics, organizations, products, channels) each cost one row.
  • Metadata reads (/v1/me, /v1/health, /v1/openapi.json) are free.
  • Search and lookup themselves are free, but the rows you then fetch are not.
  • /v1/entities/search (fuzzy discovery) is free, including the recommendations_summary it returns for entitled callers.
  • POST /v1/feedback is free — corrections never bill.

​
Commercial rows (Pro+)

Commercial intelligence endpoints — /v1/recommendations, /v1/entities/{id}/recommendations, /v1/channels/{id}/sponsors, and the enrichment items returned by /v1/mentions?details=full — bill at a higher rate per row than standard appearance rows. The recommendations pipeline is more expensive to run and curate, so each commercial row is treated as premium. A few practical consequences:
  • Pulling a 40-sponsor list is more expensive than pulling 40 appearance rows. Use limit to scope your pages.
  • details=full on /v1/mentions charges one row per appearance plus the premium rate for every commercial enrichment item attached. Omit details=full when you don’t need the commercial overlay.
  • recommendations_summary blocks on entity reads and the channel teaser cost zero rows — they’re aggregates pulled from brand_profiles and known-sponsor rollups.
/v1/me exposes recommendations_api_enabled: true|false. Use it to short-circuit commercial calls on hobby/pro keys without burning a 403.

​
Checking remaining 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
  }
}
current_spend_cents reflects on-demand spend within the current billing period. It is 0 until you actually exceed your monthly allotment and on-demand usage is enabled.

​
Exceeding your monthly allotment

ConditionOutcome
Allotment exhausted, on-demand enabledAPI continues serving requests. Each row over the allotment is billed on demand.
Allotment exhausted, on-demand disabledAPI returns 402 quota_exceeded until the next billing cycle.
You can toggle on-demand usage and set a hard spend cap in Settings → Billing.

​
Per-key tracking

Each API key tracks lifetime totals:
  • total_requests
  • total_rows_used
  • total_cost_cents
These are visible in Settings → API Keys, so you can see at a glance which key is driving usage.

​
Reducing costs

  • Cache resolved ent_<id> values rather than calling /v1/entities/lookup repeatedly.
  • Use entity_id instead of entity_name to avoid lookups embedded in mention requests.
  • Use date_from / date_to to scope mentions to the windows you actually care about.
  • Pull larger pages (up to limit=100) when iterating to amortize per-request overhead. The rows cost the same; the request count drops.