Limits & quotas

Daily quota

Each successful search takes 1 request from your daily quota.

Plan	Requests per day
Professional	500
Enterprise	1,500

The quota resets every day at 02:00, Paris time. quota.resets_at gives the exact moment in UTC.
It is shared with your dashboard on orelys.io: a search there and a search through the API take from the same quota.
Unused requests do not carry over to the next day.

What takes a request

Call	Request taken?
A search that returns results, a file or an archive	Yes
A search that completes with an empty list, or an empty file	Yes, as in the dashboard
A search the archive answers with “no results”, a refusal (`rejected`) or an error in its reply	No, within the daily allowance below
A file or archive withheld for data removal (`451 file_withheld`)	No, within the daily allowance below
An archive Orelys cannot check for data removal (`451 archive_unchecked`)	No
A search you cancel (connection closed) after it was sent to the archive	No, within the daily allowance below
A search for a removed selector	No
A search that fails — invalid input, limit reached, search service down	No
`GET /v1/me`, `/v1/buckets`, `/v1/health`	No

Daily allowance. Searches that reach the archive but bring nothing back are free up to your daily quota each day — at least 10 — shared with your dashboard. Past that, they take a request like any other search, until the quota resets. A search service that is down, busy or too slow is always free. Every search response tells you: the charged field in JSON responses, and the X-Request-Charged header on all of them.

OSINT credits

The OSINT modules never touch the daily quota: they are paid in credits.

Call	Credits
Username or Email search	1
… with `"extended": true`	4
A search where no source finds anything, or cancelled once started	0 — given back, within a daily allowance (your daily quota, at least 10); 1 or 4 past it
A search where no source could be reached	0
Invalid input, not enough credits, limit reached	0

Your balance: credits.balance in /v1/me, then credits.remaining and the X-Credits-Remaining header after each OSINT search.

Rate limits

How fast your account can search depends on your plan:

Plan	Searches a minute	Searches at the same time
Professional	60	3
Enterprise	120	5

These two limits belong to the account: searches with your API key and searches from your dashboard on orelys.io count together. A third limit applies to every address, whatever the plan.

Limit	Applies to	Code when reached
Searches a minute, per account — see the table above	the `/v1/search/` and `/v1/osint/` searches	`429 rate_limited`
Searches at the same time, per account — see the table above	the `/v1/search/` and `/v1/osint/` searches	`429 concurrency_limited`
120 calls a minute per IP address	every route	`429 ip_rate_limited`

The minute is a sliding window: a slot frees up 60 seconds after the call that used it.
Every search you send counts in the minute, even one refused for invalid input or because your searches at the same time are all in use. A search refused with rate_limited does not.
Your own numbers are in limits from /v1/me, and in the X-RateLimit-Limit header of every search.
A plan change applies from your next search.
The address limit counts searches too: from a single address, an Enterprise account’s 120 searches a minute use all of it.

Headers

Header	On	Meaning
`X-Quota-Limit`	`/v1/me`	Requests per day on your plan.
`X-Quota-Remaining`	`/v1/me`, searches	Requests left today, after this call.
`X-Quota-Reset`	`/v1/me`, searches	Next reset, ISO 8601.
`X-Credits-Remaining`	`/v1/me`, OSINT searches	Credit balance after this call.
`X-RateLimit-Limit`	searches	Searches allowed per minute on your plan.
`X-RateLimit-Remaining`	searches	Searches left in the current window.
`X-RateLimit-Reset`	searches	Seconds until the oldest search in the window expires.
`Retry-After`	`429`, some `503`	Seconds to wait before trying again.

Handling `429`

Wait for Retry-After seconds, then try again. quota_exceeded is different: the daily quota is used up, and Retry-After points at the next reset — retrying sooner will not help.

import time
import requests

def search(session, mode, body, tries=3):
    for _ in range(tries):
        response = session.post(f"https://api.orelys.io/v1/search/{mode}", json=body, timeout=45)
        if response.status_code != 429:
            response.raise_for_status()
            return response
        error = response.json()["error"]
        if error["code"] == "quota_exceeded":
            raise RuntimeError(error["message"])
        time.sleep(int(response.headers.get("Retry-After", "1")))
    raise RuntimeError("Still rate limited, try again later.")

Keep no more searches running than your plan allows — 3 on Professional, 5 on Enterprise (limits.concurrent_requests in /v1/me). The rest are refused rather than queued.

Get started

Essentials

Searching

Daily quota

What takes a request

OSINT credits

Rate limits

Headers

Handling `429`

​Daily quota

​What takes a request

​OSINT credits

​Rate limits

​Headers

​Handling 429

Daily quota

What takes a request

OSINT credits

Rate limits

Headers

Handling `429`