Errors, Rate Limits & Credits

Requests are metered two ways - how fast you call, and how many credits you spend. Both are visible in your responses, so there are no surprises.

Request rate

Requests are rate-limited per token, by default about 1 request per second per endpoint. Sending faster returns 429:

{
  "detail": "rate limit exceeded"
}

Pace your calls and use Pagination to collect large result sets.

Credits

Every request consumes credits from your plan:

• Searches over the last 31 days cost 1 credit; older windows cost 2-4 - see Time Range & History.
• Segmentation requests cost 1 credit.
• requests_left in every response shows your remaining balance.

When your balance runs out, requests return 429 with an insufficient-credits message.

Error responses

Errors are JSON with a detail field:

{
  "detail": "Unknown API token"
}