Billing units and plans
What consumes a unit, what never does, and the limits each plan enforces.
Usage is metered in four units. Every billable request writes its units to the workspace ledger before the response returns, and that ledger is what you are charged from. Reporting is a read of it: GET /v1/usage and the dashboard can trail the ledger by up to five minutes, so a total taken seconds after a bulk run may still be climbing.
| Unit | Consumed by | Amount |
|---|---|---|
lookup_cached | A matched or stale store profile from existing observations | 1 per store |
lookup_live | A scan queued by refresh: true | 1 per queued domain, at queue time |
history_query | One page of store history or signal search (later release) | 1 per page |
refresh_requested | Reserved for explicit scan requests (later release) | 1 per domain |
What is never billed
- A
no_matchresult, whatever the reason. Unknown domains cost nothing to ask about. Queueing a scan for one is a separate charge: withrefresh: true, the lookup stays free and each queued domain costs alookup_liveunit at queue time. - A
404 not_foundonGET /v1/stores/{domain}. - Any error response (4xx or 5xx).
- An idempotent replay (
Idempotent-Replayed: true). GET /v1/account,GET /v1/usage,GET /v1/technologies, andGET /v1/health.
A stale profile is billed like a fresh one: the data is real, just older than the plan's freshness window, and the stale flag lets you decide whether a refresh is worth a lookup_live unit.
Plan limits
Limits are enforced from the workspace plan at request time and returned on GET /v1/account as plan.limits. The table below is the current default per plan; the values on the account endpoint are authoritative for your key.
Enrich batch is the per-request domain cap for your plan, returned as plan.limits.enrich_batch_max. 100 is the contract maximum, not a universal default.
| Plan | RPM | Concurrency | Enrich batch | Included lookup_cached / period | Freshness window | Live refreshes / period |
|---|---|---|---|---|---|---|
| Free | 30 | 2 | 25 | 25 | 30 days | 0 |
| Pro | 120 | 5 | 100 | plan-defined | 30 days | 100 |
| Growth | 300 | 10 | 100 | 10,000 | 30 days | plan-defined |
| Partner | negotiated | negotiated | 100 | metered | negotiated | metered |
When the included allowance is used up, non-partner keys receive 402 payment_required with a reset_at timestamp. Partner keys continue and are metered.
Reading your usage
GET /v1/usage returns the current period totals and a per-key breakdown, including revoked keys that consumed units this period so the numbers reconcile. As above, these totals are a report and can trail the ledger by up to five minutes. Every response also carries X-Usage-Remaining for the lookup_cached unit, so a bulk run can stop before it hits the wall.
Prices per unit are on the pricing page. This page describes what a unit is, not what it costs.