YaqeenDocs
Back to Yaqeen

Reference

Rate limits and pagination

The call limits, the size limits, the list paging rules and the idempotency header, as the code sets them.

This page lists the limits that can refuse or shorten a call.

Throttle scopes#

A throttle counts calls in a time window and answers 429 when a caller is over the limit. Each scope has its own counter. The counter is per signed-in account. A caller who is not signed in is counted by network address.

ScopeLimitEndpoints
login10 a minutePOST /auth/login/, POST /auth/invite/accept/, POST /auth/password/reset/
login_name5 a minutePOST /auth/login/, counted per username and network address
login_account20 an hourPOST /auth/login/, counted per username from any address
password10 an hourPOST /auth/password/
decision60 a minuteHold decision, bulk decision, appeal decision, approval decision, application decision
ingest30 an hourPOST /ingest/feed/, POST /ingest/connect/, POST /scoring/runs/
hook120 a minuteThe trust pages (/trust/status/, /trust/controls/, /trust/incidents/)
assistant40 a minutePOST /assistant/chat/
assistant_act30 a minutePOST /assistant/act/
mcp120 a minutePOST /mcp/ (the MCP endpoint for Claude and Codex)

A request that is over a limit gets 429, the header Retry-After (seconds to wait) and this body:

json
{ "code": "error", "message": "Request was throttled. Expected available in 30 seconds.", "fields": null }

API key limits#

A key has two more limits. They apply only to calls made with a bearer key.

LimitValueWhen over
Per key, per minuterate_per_minute on the key, 1 to 6000, default 120429 and Retry-After with the seconds left in the current minute
Per organization, per daydaily_api_calls in the plan, default 50,000. A value of 0 means no limit.429 and Retry-After: 3600

The daily count uses the Riyadh calendar day. When a measure passes 80 percent of its plan limit, Yaqeen sends one alert a day to the alert channels, if any are set up. An admin can lower the limits with PUT /api/v1/usage/plan/. Raising one past the plan needs us.

Size limits#

LimitValueError
Rows in one POST /ingest/feed/ or POST /ingest/connect/ call5,000400, with rows in fields
Zip upload300 MB413 too_large
Any other request body sent through the site's address10 MB413 from the proxy, as an HTML page, not JSON
Holds in one bulk decision50400 with the field name in fields
Appeal file1 byte to 10 MB, PDF, JPEG or PNG400 bad_size, 400 bad_type
Files on one appeal5409 too_many_documents
Audit export range92 days, at most 20,000 rows400 bad_range
Scoring recent_days1 to 60, default 7400
Active webhook endpoints5409 too_many
Saved views per person30409 too_many_views
Assistant message2,000 characters400 too_long
One MCP message64 KB413 too_large

Sign-in limits for Claude and Codex#

The OAuth endpoints under /api/v1/oauth/ have their own counters, kept per network address: 60 a minute for the sign-in page and for token requests, 10 an hour for client registration and 60 a minute for revoking. The password step on the sign-in page also allows 8 tries in 15 minutes per username. Over a limit, the token and register endpoints answer 429 with slow_down.

Pagination#

List endpoints that can be long use limit and offset paging. Send limit and offset as query parameters.

ParameterDefaultRule
limit25The most rows to return. A value above 100 is cut to 100. A value that is not a positive whole number is ignored and the default is used.
offset0How many rows to skip. A bad value is ignored and 0 is used.

The response has this shape:

json
{ "count": 83, "next": "https://api.example.test/api/v1/holds/?limit=25&offset=25", "previous": null, "results": [] }

count is the total number of rows that match. next and previous are full addresses, or null at the ends. Follow next until it is null.

bash
curl "https://api.example.test/api/v1/holds/?status=approved&limit=100&offset=0" \
  -H "Authorization: Bearer yq_live_..."

These endpoints are paged:

  • Holds and stores: /holds/, /holds/{id}/orders/, /stores/, /owners/, /payouts/
  • Review work: /cases/, /cases/{id}/notes/, /cases/{id}/outcome/, /approvals/, /intake/, /suppressions/, /reserves/, /reserves/disputes/
  • Records: /audit/, /privacy/requests/, /users/, /jobs/, /ops/errors/
  • Other: /webhooks/{id}/deliveries/, /notifications/, /assistant/chats/

Other list endpoints, such as /keys/, /webhooks/, /rules/ and /views/, return the whole list as a plain array.

Idempotency#

The Idempotency-Key header works on POST /holds/{id}/decision/ and POST /holds/bulk-decision/ only. The key is 8 to 128 letters, digits, - or _. Yaqeen keeps the first answer for 24 hours. The same key with the same body returns that answer with Idempotent-Replayed: true. The same key with a different body gets 422 idempotency_key_reused. A second request while the first is running gets 409 in_progress. Read Safe retries for the steps.

Up Down to moveEnter to openEsc to close