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.
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.
Other data endpoints	10 requests/sec	Per client key.

Going over a limit returns 429. Retry with exponential backoff; at 10 requests/sec against the 10,000-item batch endpoint the ceiling is 100 million 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.

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.
Topic-to-people / topic-to-companies queries	Per record returned in the page.
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 resolution endpoints	Per resolved record, by resolution depth (HEM only, HEM + PTE, or full profile).
Events API	Per event record pulled.

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

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: 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.