Skip to main content
The Notra 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, so 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 does not run the request.

​
Limits

Notra keys each limit in one of three ways:
  • Per key. The bucket belongs to the API key making the request, so 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 apply across all projects in the organization, so four scans per hour is the total across every project, not four per project.

​
Feedback

Agents call POST /v1/feedback/{organizationSlug} without credentials. Because it is the only such endpoint, Notra limits it per source IP address and per organization, and 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 the API rejects a request, it returns:
reset is a Unix timestamp in milliseconds, while 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, and it means the authentication layer is throttling the key itself. See Authentication.

​
Best practices

  • Read RateLimit-Remaining and slow down before you hit zero.
  • On 429, wait for Retry-After seconds before retrying instead of retrying immediately.
  • Use exponential backoff with jitter for 5xx responses, but treat 429 as a hard wait rather than a retry signal.
  • GEO scans are the most expensive thing a key can trigger, so 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 instead of sending them in bursts.

​
Need higher limits?

If your workload needs higher limits, contact us 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 October 8, 2026