Rate Limits & Usage

Skywalk API meters usage so that your integrations stay predictable and our system stays healthy. There are two independent limits:

a per-second rate limit — exceed it and the request is rejected with 429 and a Retry-After header telling you when to try again;
a monthly usage quota — the credits your plan includes each calendar month, reported on every response in the X-RateLimit-* headers.

Projects and keys

Limits apply to your project. All of a project's API keys draw on the same monthly quota and the same per-second rate limits, and an API key identifies which application is calling. In practice:

all of a project's keys share one set of limits, however many keys it has;
a newly created key works immediately, at your project's limits;
revoking one key leaves the others unaffected;
every billable request records which key made it, so usage can be attributed back to a specific integration.

Per-second rate limits

Rate limits are enforced per project, separately for reads and writes.

Limit	Applies to	Sustained rate	Burst
Read	`GET` requests	1 request/second	5 requests
Write	`POST` requests	1 request/second	1 request

When you exceed a rate limit, the API responds 429 with a Retry-After header, in whole seconds:

Wait out Retry-After and re-issue the identical request. A retried request is not billed for the rejected attempt — error responses are always free.

Rate limit response

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

{
"statusCode": 429,
"type": "UNKNOWN",
"message": "Rate limit exceeded. Retry after 1 second(s).",
"errors": []
}

The sustained rate is how many requests per second are accepted on average; the burst is how many can arrive back to back before that rate applies. Writes have no burst allowance, so space them at least a second apart.

If your integration needs higher limits, contact us.

Monthly usage quotas

Quotas are counted in credits per calendar month, in UTC, and reset at 00:00:00 UTC on the first of the following month. A successful request costs 1 credit — it returns one page of data.

Quota	Counts	Standard plan
Read	Successful `GET` responses, 1 credit per data page	10,000 credits / month
Write	Accepted `POST` requests, 1 credit each	1,000 credits / month

Trial projects start with a smaller read quota and without write access — a request class your plan does not include returns 403. Your project's current quota is in the X-RateLimit-Limit header and on the dashboard Usage page.

Exceeding your quota

Your monthly quota is the usage your plan includes. If your project needs more, contact us to update the plan — a change takes effect immediately for every key on the project.

Requests over the quota may be rejected with 429. Retry-After on this response is the number of seconds remaining in the month, and the X-RateLimit-* headers ride along so you can see the position you are in.

The two 429s are distinguishable by their message and by the size of Retry-After: a rate-limit Retry-After is a second or two, a quota Retry-After is the remainder of the month.

Quota exceeded response

HTTP/1.1 429 Too Many Requests
Retry-After: 1209600
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1788220800

{
"statusCode": 429,
"type": "UNKNOWN",
"message": "Monthly apiRead quota exceeded (10000 credits). Contact support to update your plan.",
"errors": []
}

Rate limit headers

Every metered response carries your monthly quota position for the class of the request you just made — GET requests report your read quota, POST requests report your write quota.

Header	Meaning
`X-RateLimit-Limit`	Your project's monthly quota for this request's class.
`X-RateLimit-Remaining`	Credits left this month for this request's class, shared by all of the project's keys. Never negative.
`X-RateLimit-Reset`	Unix timestamp (seconds) of the first instant of next month, UTC — when `Remaining` returns to `Limit`.

Response headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 7431
X-RateLimit-Reset: 1788220800

Two things to know when you build against these headers:

They describe the monthly quota. There is no header countdown for the per-second rate limit; Retry-After on a 429 is the signal for that.
Remaining is approximate. It may trail your most recent requests slightly, so leave yourself some headroom.

Browser-based JavaScript cannot read these headers cross-origin. API keys are server-side credentials — see Authentication — so read the headers from your server.

What counts as usage

The billable unit is a credit: a response that returns a page of data costs one.

Billed — one credit each:

every successful GET that returns data, including a response served from the data cache;
the request that starts a background refresh, even though it comes back meta.status: "updating" with no fresh data yet. Starting the refresh is the billable act: the work runs whether or not you come back for the result;
each page you fetch while paginating — a request returning links.next bills a credit for the page it just returned, and the next cursor request bills its own. This includes paging through data you already have while a refresh runs in the background;
a successful GET whose meta.status is stale — it still returned data;
a GET that returned an empty data array;
every accepted POST, counted against your write quota.

Free — never billed:

any error response (anything that is not a 2xx), including the 429s above;
polling a pending refresh — a re-fetch of the first page whose meta.status is updating, which is what a polling loop does. Free however many times you poll, until the refresh comes back with fresh data;
a response whose meta.status is error;
authentication and connection endpoints under /v1/mcp used by the MCP server's OAuth flow.

The recommended polling loop — request, get meta.status: "updating", wait 10 seconds, retry — costs you exactly one credit no matter how many times you poll: the first request bills because it starts the refresh, and every poll after it is free. Rate limits still apply to polls, so keep the 10-second interval.

Traffic from AI agents

Requests the Skywalk MCP Server makes on your behalf are metered separately from your own applications' traffic, so agent activity does not count against your direct limits. The MCP server honours short Retry-After waits itself, so a rate-limited report slows down rather than failing; a report that runs out of monthly quota does fail.

Authentication

How API keys authenticate your requests.

Get an API Key

Create, name and revoke keys from the Dashboard.