Skip to main content
The Kolaria API rate limits the endpoints that start model runs, scans or other expensive work. Plain reads (listing posts, visibility data, feedback, schedules and so on) and deletes are not rate limited. Each limited endpoint has its own bucket with a sliding window. Hitting the post-generation limit does not affect post updates or GEO scans. When a request would exceed a limit, the API returns 429 Too Many Requests and the request is not executed.

​
Limits

Limits are keyed in one of three ways:
  • per key: the bucket belongs to the API key making the request. Two keys in the same organization have separate budgets.
  • per organization: every key in the organization shares one bucket.
  • per IP: the bucket belongs to the caller’s source address.

​
Content

​
Chats and Agent

​
GEO

GEO limits span all projects in the organization: four scans per hour is the total across every project, not four per project.

​
Feedback

POST /v1/feedback/{organizationSlug} is the one endpoint agents call without credentials, so it is limited per source IP address and per organization. Both limits apply at the same time. See Agent Feedback.

​
Response headers

Every response from a rate-limited endpoint, successful or not, includes both the IETF draft header names and the legacy X- names: Endpoints that are not rate limited do not send these headers.

​
429 response

When a request is rejected, the API returns:
reset is a Unix timestamp in milliseconds. The Retry-After header gives the same moment as a number of seconds to wait and is the simplest field to act on.
A 429 with error: "API key rate limit exceeded" and a code field comes from the authentication layer rather than an endpoint bucket. It means the key itself is throttled. See Authentication.

​
Best practices

  • Read RateLimit-Remaining proactively and slow down before you hit zero.
  • On 429, wait for Retry-After seconds before retrying. Do not retry immediately.
  • Use exponential backoff with jitter for 5xx responses; treat 429 as a hard wait, not a retry signal.
  • GEO scans are the most expensive thing a key can trigger. Poll GET /v1/projects/{projectId}/geo/scans/{scanId} for the result instead of re-triggering.
  • For bulk work (for example backfilling many posts), space requests evenly across the window rather than bursting.

​
Need higher limits?

If your workload genuinely needs higher limits, reach out via GitHub and describe the use case and expected volume.

​
Next Steps

Getting Started

Explore the endpoint groups

Authentication

Scopes and auth errors
Last modified on September 29, 2026