Rate Limits and Metering

The short version

Billing is usage-based: you pay per record returned, with no monthly floor. Unmatched lookups are free.
Every intent endpoint accepts "dry_run": true to see the exact billable count before a live run. Dry runs bill nothing.
Default rate limit on intent endpoints is 10 requests per second per organization. Most other API routes are limited at 10 requests per second per client.
The Events API has its own limit: 720 requests per minute per organization (burst of 25).
Batch endpoints take up to 10,000 items per call, so high volume rarely needs high request rates.

Rate limits

Surface	Limit	Notes
Intent endpoints (`/api/v1/intent/*`)	10 requests/sec per organization	Shared across all intent endpoints. Higher limits are available per contract; ask your Delivr contact.
Intent preview endpoints (`/api/v1/intent/*/preview`)	5 requests/sec per organization	Previews return capped samples and bill nothing.
Events API (`/api/v1/events`, `/api/v2/events`, `/api/v3/events/*`)	720 requests/min per organization, burst of 25	Shared across all Events API routes and keys in the organization. Higher limits are available per contract; ask your Delivr contact.
Other data endpoints	10 requests/sec	Per client key. Does not apply to the Events API.

Going over a rate limit returns 429. On the Events API the response carries a Retry-After header (in seconds); wait that long before retrying. It does not send X-RateLimit-* headers. Retry with exponential backoff; at 10 requests/sec against the 10,000-item batch endpoint the ceiling is 100,000 lookups per second of wall time, so request rate is almost never the real constraint. If it is for you, raise it with your Delivr contact rather than working around it.

Usage limits

Separately from rate limits, Delivr applies a daily and a monthly usage limit per meter. A request that would go past one is refused with 429 and a body whose error is platform_cap_exceeded, so check error before retrying a 429. Its kind says what to do:

`kind`	What to do
`limit_reached`	The same request succeeds after `resets_at`: midnight UTC for a daily limit, the 1st of next month (UTC) for a monthly one. `Retry-After` gives the wait in seconds.
`request_too_large`	This request alone is larger than the limit, so retrying cannot succeed. Send a smaller request, or contact support to raise the limit.
`shut_off`	Usage is paused for this account. Contact support.

message says the same in a sentence you can show your users. The API reference shows the full body on every endpoint that can return it.

What gets billed

Delivr bills on usage meters. The ones you will meet through the API:

What you did	What is billed
Intent lookup or batch (person or company)	Per matched record. `matched: false` results are free. A person lookup matches through any address the person holds, so a `dry_run` count can be higher than when each address was read on its own.
Topic-to-people / topic-to-companies queries	Per record returned in the page. People rows are persons, one per person.
Preview endpoints (`/preview`)	Nothing. Capped at 25 records, built for evaluation.
`"dry_run": true` on any intent endpoint	Nothing. Returns the count a live run would bill.
Identity lookup (`/api/v1/lookup`, `/api/v1/lookup/batch`, `/api/v1/contact/query`)	Per record returned (`contact_record`); `/api/v1/contact/query` bills only records that carry a business email. Misses, filtered-out records, and per-key errors are free. The batch route is also limited to 2 requests per second per organization.
Identity resolution endpoints	Per resolved record, by resolution depth (HEM only, HEM + PTE, or full profile).
Events API	Per record returned on a `2xx` response, on the meter set by the identity fields in the records. See Events API metering.

Usage accrues to your organization and bills through Stripe at the volume rates on your order form. Pricing brackets are on the pricing page.

Events API metering

The Events API bills per record returned, on a single meter per response:

Records contain	Meter
Event fields only	Events / Journey
Identity or profile columns	The matching Resolution meter: HEM only, HEM + PTE, or Full Profile

The highest tier present wins. A response is never billed on two meters.
On /api/v3/events/{tier} the route sets the meter. See Events API v3.
A tier route bills every event it returns, whether or not the visitor was identified. Add filter=resolved:eq:true to return, and pay for, identified visitors' events only.
Each event is a record, so a visitor with five page views is five records. The /api/v3/events/{tier}/visitors route returns one row per person, and each person it returns is billed once per request.
On other events routes, an explicit select sets the meter from the fields you list. Without select, the meter follows the identity columns actually returned.
Repeat reads bill again.
Not billed: events_schema, scan estimates, event_counts, event_counts_index, the v3 /schema routes, /api/v3/events/web_event/counts, non-2xx responses, empty results, and test-environment keys.
Pixel capture (ingest) is not billed.

Predict cost before you spend: dry_run

Any intent request becomes a free cost preview by adding one field:

curl -X POST "https://api.delivr.ai/api/v1/intent/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"id": "r1", "email": "[email protected]"}], "dry_run": true}'

{
  "dry_run": true,
  "meter": "intent_signal_scored",
  "records_to_charge": 1
}

The request is fully resolved server-side, so records_to_charge is exact, not an estimate. A recommended pattern for large jobs: dry-run the batch, confirm the count is what you expect, then re-send without the flag.

Evaluate for free: previews

The discovery endpoints have preview variants that return real records, capped at 25, with no billing:

POST /api/v1/intent/people/preview
POST /api/v1/intent/companies/preview
POST /api/v1/intent/people/multi/preview
POST /api/v1/intent/companies/multi/preview

Previews return the top of the ranked result plus the full audience count, so you can judge quality and size before importing anything. Emails and LinkedIn URLs are masked in previews; the unmasked identifiers come with the paid endpoints.

Timeouts and retries

429 with error platform_cap_exceeded: a usage limit, not a rate limit. Follow its kind (see Usage limits above) instead of retrying.
Any other 429: back off exponentially (start at 1 second, double each retry).
5xx: safe to retry; lookups are read-only and idempotent.
Client timeouts: allow 60 seconds on full 10,000-item batches.