Rate limits#

Each API key has its own budget, enforced by two limits that apply together. A request must satisfy both:

On a self-hosted instance these are configurable with API_THROTTLE_BURST and API_THROTTLE_SUSTAINED, see Configuration.

When you exceed a limit#

Exceeding either limit returns:

HTTP 429 Too Many Requests

{ "detail": "Request was throttled. Expected available in 12 seconds." }

DRF includes a Retry-After hint in the message; back off and retry after the indicated time. A robust client should handle 429 with exponential backoff.

Usage counting#

Each search request counts toward the key owner’s monthly search total (the same total shown for website searches in Settings). This includes:

web/, images/, images/similar/ (only when a real search runs), news/, videos/, maps/, translate/, translate/languages/, instant/, cards/ and suggest/.

The meta endpoints do not count toward usage:

• The API root (/api/v1/)
• status/
• key/

So you can poll key/ or status/ freely to check health without spending your search budget (they still count against the raw rate limit).