Rate limits

The API has no fixed per-second request quota today. Usage is bounded by the plan gate and by caps on how much data a single response returns.

The plan gate

API access is a Studio-and-above capability. A key on a lower plan is rejected on every endpoint with 403 and {"upgrade": true}. See Authentication.

Response caps

Read endpoints cap the number of detail rows in one response. Summary totals stay complete.

Endpoint	Cap	What's capped
GET /_naulon/earnings/statements	10,000	Per-author line items. Totals stay exact.
GET /_naulon/earnings/reconciliation	1,000	Open exception rows. Bucket totals stay exact.
GET /_naulon/earnings/export.csv	50,000	Rows in the export.

A clipped response always says so:

• statements sets truncatedLines: true on the statement whose line items were cut.
• reconciliation sets truncatedExceptions: true on the body.
• export.csv has no JSON body to carry a flag, so it answers with x-naulon-truncated: true and x-naulon-row-count headers. Read them before you treat a download as a complete ledger.

Paging

GET /_naulon/earnings returns recent crossings newest-first with a nextCursor. To walk the full history, pass the cursor back as ?cursor=<value> until the response omits it. Page in order rather than requesting wide windows repeatedly.

Fair use

If you pull data on a schedule, cache it and poll every few minutes, not every few seconds. Back off on errors. If the read API gets a hard rate limit, a throttled request will return 429 and this page will say so.

Agent MCP sessions

Each agent token may open 120 MCP sessions an hour and hold 5 open at once. A client normally opens one session when it starts and reuses it, so the limit only affects a client that reconnects per call or a script that starts a fresh claude -p for every task.

Past the hourly figure, a new session gets 429 with rate_limited and a Retry-After naming when to try again. Sessions already open keep working. At five open, the least recently used one is closed to make room once it has sat idle for a minute, so a client that crashed without closing its session is not locked out. Five sessions all busy at once get 429 with too_many_sessions and the wait until a slot frees. Paid questions through naulon_read and naulon_answer carry their own hourly limit, described in For buyers.

Domain checks

Checking a domain makes our servers fetch a hostname you typed, so checks are capped two ways: per account per hour, and across all accounts per hostname. Setting up a domain stays well under both.

A throttled check returns 429 with a Retry-After. Nothing you set up is lost. Once you have proven you own a hostname, the per-hostname cap stops applying to you, so nobody else checking that domain can crowd you out of your own setup.