Rate limits

There's no fixed per-second request quota on the API today. What bounds your usage is the plan gate and a few caps on how much data a single response returns. Be a good client anyway: back off on errors and page through large result sets rather than polling in a tight loop.

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}. This is the main control on who can call the API at all; see Authentication.

Response caps

Read endpoints keep their summary totals complete but cap the number of detail rows in a single response, so a busy site can't pull an unbounded payload in one call:

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 cap never clips silently, and the totals above a clipped list stay complete: the cap bounds the payload, not the math. How each one tells you:

• 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're pulling data on a schedule, cache it and widen your interval rather than polling every few seconds. If the read API ever grows a hard rate limit, a throttled request will return 429 and this page will say so.

Domain checks

Checking a domain makes our servers fetch a hostname you typed, so those checks are capped two ways: how many one account runs in an hour, and how many everyone together runs against one hostname. Both sit far above what setting a domain up costs, so normal use never meets them.

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.