Rate limits

RolesAPI limits requests per minute (rpm) by plan. Limits apply per account, across all keys. Credits and rate limits are independent: credits meter how much data you consume, rpm meters how fast you can ask for it.

What is my limit?

Plan	Requests per minute	Credits included
Free	20	100 (one-time)
Monthly ($5/mo)	200	1,000/mo
Annual ($54/yr)	300	12,000/yr

What happens when I exceed it?

The request is rejected with HTTP 429 and a Retry-After header giving the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 20 requests per minute on the free plan. Retry after 12 seconds.",
    "request_id": "req_4a8e91c3"
  }
}

Rate-limited requests consume no credits.

How should my client behave?

• Respect Retry-After. Sleep for the given seconds before retrying. Do not busy-loop; repeated requests inside the window are also rejected and prolong the wait.
• Smooth your bursts. The window is per minute, but sending your whole minute’s budget in the first second risks tripping the limit when polling or webhook handlers add their own calls. A simple client-side throttle (e.g. one request every 60 / rpm seconds) keeps you comfortably inside the limit.
• Budget for polling. Job-status polls count against the same limit as data calls. Poll every few seconds, not in a tight loop — or use a webhook and do not poll at all.

What if I need more throughput than my rpm allows?

Do not fan out requests — hand the work to the API. Async jobs are the high-volume path:

• POST /v1/roles/batch accepts up to 500 roles in a single request.
• POST /v1/search/with-details runs a search and fetches every role’s details server-side.

One request enqueues the whole workload; you then poll one job or receive one webhook. A 500-role batch costs one request against your rpm instead of 500, while credits are charged per processed role as usual.

If you are sustaining high volume, the annual plan’s 300 rpm plus batch endpoints covers most pipelines. For anything beyond that, contact nikhil@landkit.pro.