What you are billed for#
Devices with call blocking enabled, not lookups.The count is the number of distinct devices that reported in during a calendar month with the feature turned on. One device that runs a thousand lookups counts once. A device that runs none still counts, if it reported in.setFeatureEnabled(false) takes a device out of the count. Use it when a user turns your caller ID feature off, so you do not pay for them.Sandbox and active#
Every app you create starts in sandbox. | Sandbox | Active |
|---|
| Price | Free | Agreed per device |
| Device cap | 200 in a calendar month | The cap you agreed |
| Lookup data | The same real data | The same real data |
| Rate limits | The same | The same |
| How you get it | Self-service, right away | Contact us |
Sandbox is not a test mode with fake answers. Lookups return the same data as production. The only difference is the cap.What happens at the cap#
Devices already counted this month keep working. New devices are refused with 402 and sandbox_limit_reached.The failure looks strange in the field. Your existing testers are fine while every new install fails, so check your device count before you debug anything else.Going live#
Contact us to agree a price. We switch your app to active and set your cap.No code changes. Nothing in your app refers to sandbox or active.Rate limits#
Per device unless stated. Hitting one returns 429 with a Retry-After header.| What | Limit |
|---|
| Lookups | 120 per minute |
| Authentication | 5 per minute, and 10 per minute per IP address |
| Usage report | 6 per hour |
| Block list download | 5 per minute |
The lookup limit allows a burst of call screening while making bulk downloads of the data impractical. Normal use never reaches it.If you hit the authentication limit during development, you are probably restarting the app in a loop. A session lasts 30 minutes, so a normal app authenticates rarely.Other limits#
| What | Limit |
|---|
| Apps per account, self-service | 50 |
| Session length | 30 minutes, refreshed by the SDK |
| Default usage report interval | 24 hours |
| Lookup timeout | 2500 ms, configurable on Android and iOS |
| Background transfer timeout | 30000 ms, configurable on Android and iOS |
Where to read your usage#
Why your dashboard can read zero while lookups work#
On Android, lookups need SDK_KEY and SDK_SECRET. Device counting needs CLIENT_KEY as well.Leave out CLIENT_KEY and everything works, while the dashboard stays empty and you are billed for nothing. That sounds good until an audit. Add all three.On iOS, add the extension usage report by calling bootstrap with your lcidClientKey. See iOS add the extension.Keeping the count honest for users who never open your app#
Usage reports normally ride along with app launches. A user who installs your app and never opens it again still uses the feature. The extension and the screening service run without your app.Two things keep that reported:Android: nothing to do. The SDK schedules the report itself.
iOS: pass heartbeatTaskIdentifier to bootstrap, and list it in BGTaskSchedulerPermittedIdentifiers in your Info.plist. Without it, reporting stops when the user stops opening your app.
Which region your data comes from#
Every SDK talks to https://api.callerapi.com by default. Live Caller ID on iOS 18 talks to pir.callerapi.com and pat.callerapi.com.Contact us if you need a regional endpoint, or hosts reserved for your company. On Android you can then point the SDK with the API_BASE manifest entry, and on iOS with apiBase in CallerAPIConfig.Modified at 2026-07-29 23:18:55
