> ## Documentation Index
> Fetch the complete documentation index at: https://devs.surferseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits and credits

> Stay under the request limits and know which operations spend credits.

Requests share a limit when they use the same API key and endpoint, in both API versions. Only the three v2 operations below spend credits or count toward an allowance; every other v2 request, reads included, does neither.

## Limits

Every endpoint in this reference allows 10 requests per second per API key unless the table says otherwise, and the limits are the same on every plan.

| Endpoints | Limit |
| - | - |
| Every other endpoint in this reference, v1 and v2 | 10 requests per second |
| `POST /api/v1/serp_analyzers/batch` ([Create a batch of SERP Analyzer queries](/api/v1/serp-analyzer/create-a-batch-of-serp-analyzer-queries-post-create-batch)) and its deprecated alias `POST /api/v1/serp_analyzer/batches` | 10 requests per minute |
| `POST /api/v1/ai_detector/detect` ([Detect AI content in a text](/api/v1/other/detect-ai-content-in-a-text)) | 60 requests per minute |

Requests with different resource ids share a limit when their method and route pattern match. Ten requests for ten different Content Editors count as ten against `GET /api/v2/workspaces/{workspace_id}/content_editors/{id}`. A burst against one endpoint does not slow the others.

Windows are fixed, not sliding: the counter resets at the end of each second or minute. Each v2 reference page prints its limit at the end of the operation description; a v1 page that prints none uses the default.

## Headers

Every v2 response to an authenticated request reports the window it was counted in, including the `429` itself.

| Header | Meaning |
| - | - |
| `x-ratelimit-limit` | Requests allowed in the current window for this endpoint and API key. |
| `x-ratelimit-remaining` | Requests left in the current window. `0` means the next request is rejected. |
| `x-ratelimit-reset` | Unix timestamp, in seconds, at which the current window resets. |

Authentication runs before the counter, so a `401` carries none of them. v1 responses carry none either.

In a loop, read `x-ratelimit-remaining` after each response and pause until `x-ratelimit-reset` when it reaches `0`. Other processes on the same key draw on the same allowance, so still handle `429`.

## Over the limit

A request over the limit is rejected before it does any work, with a `429` that says how long to wait.

In v2 the wait arrives twice, in the `Retry-After` header and inside the [error envelope](/api/errors), both in whole seconds. The body repeats it in `details`:

```json theme={"system"}
{
  "error": {
    "reason": "rate_limit_exceeded",
    "details": [{ "retry_after": 1 }]
  }
}
```

Surfer rounds the wait up and never reports less than `1`, so the default one-second window always answers `1` and the per-minute windows answer up to `60`. The three window [headers](#headers) come with the response, with `x-ratelimit-remaining` at `0`.

v1 answers with the plain-text body `Rate limit exceeded. Try again in N ms`, where `N` is the wait in milliseconds, and sends no headers. [Migrating from v1](/api/migrating-from-v1) lists the other differences.

## Handle `429`

Wait for `Retry-After` before retrying the rejected request.

* Resend the same request after the wait; in v1 the wait is the milliseconds the body names. The rejected request did not run, so resending it is safe; a request that timed out is a different case, covered under [Idempotent creates](/api/requests#idempotent-creates).
* Spread bulk work instead of bursting. At the default limit, one request every 100 milliseconds per endpoint stays under it.
* Pace by the headers rather than by a fixed sleep when several processes share one key, because they share its allowance too.

## Credits

Each operation spends at most one credit, or one use of its allowance, per request, at the moment its Cost cell names.

| Operation | What it does | Cost |
| - | - | - |
| [Create Content Editor](/api/v2/content-editors/create-content-editor) | Builds the document Surfer creates around a keyword, with its guidelines and scores. | One Content Editor credit when a new editor is created. An [idempotent replay](/api/requests#idempotent-creates) and a failed initialization do not count. |
| [Create AI Article](/api/v2/ai-articles/create-ai-article) | Generates an article inside a Content Editor. | On Enterprise and some older plans, one AI Article credit when generation starts, and on those plans the Content Editor itself is not charged. Other plans include AI Articles in the Content Editor and spend nothing beyond the editor. |
| [Start Auto-Optimize](/api/v2/auto-optimize/start-auto-optimize) | Applies optimization changes to the editor's document. | Counts toward your plan's Auto-Optimize allowance when a run starts. |

Each reference page repeats this as a Cost or Usage line under the operation description.

Deleting a Content Editor does not refund its credit, and the deleted editor still counts toward fair usage ([Delete Content Editor](/api/v2/content-editors/delete-content-editor)).

In v1, [creating a Content Editor](/api/v1/content-editors/create-content-editor-query) spends one Content Editor credit; on Enterprise and some older plans, a create with `write_with_ai` spends an AI article credit instead. Auto-Optimize, Audit, SERP Analyzer, and Humanizer draw on their own allowances.

## When an allowance is used up

The request fails with `422` and reason `quota_exceeded`; check **Settings → Usage** and your plan allowance before retrying. The `message` names the allowance, for example `Content Editor quota exceeded` or `Auto-Optimize allowance exceeded`.

Creating a [content template](/api/v2/content-templates/create-content-template) or a [custom voice](/api/v2/custom-voices/create-custom-voice) answers the same way when you reach the number your plan allows. Those are caps on how many you can hold, not credits spent per request, so delete unused ones before creating more.

> [!NOTE]
>
> No endpoint reports remaining credits, so check the app before a bulk run that
> creates Content Editors or generates articles.

The allowances themselves depend on your plan:

* Documents per plan: the [pricing page](https://surferseo.com/pricing/).
* Auto-Optimize allowance: your plan's limits; plans on fair usage follow the [Fair Usage Policy](https://docs.surferseo.com/en/articles/12944161-fair-usage-policy).
* Allowances for SERP Analyzer, Audit, and Humanizer, and the caps on templates and voices: the [Fair Usage Policy](https://docs.surferseo.com/en/articles/12944161-fair-usage-policy).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.