Pricing & quotas

Each distinct URL admitted through a scrape endpoint or `/analyse` spends **credits** from the monthly pool tied to your plan. Plan concurrency caps running **URL jobs** across `/scrape`, `/analyse` and `/map`. Map uses the same scheduler and concurrency allowance but does not consume credits.

## Credit cost per engine

Cost is charged **per URL**, keyed by the engine you request (a multi-URL request costs the sum).

| Engine | Credits / URL |
|---|---|
| `html` | 1 |
| `json` | 1 |
| `analyse` | 3 |
| `browser` | 5 |
| `ai` | 50 |

`analyse` is one fetch + one LLM pass. AI reserves 50 credits once for one queued job; internal HTML/JSON/browser calls do not reserve additional credits. AI shares browser capacity for its full run and also obeys its own concurrency cap and the user plan. Map is not metered. `scrape_markdown` uses the selected engine’s price: 1 credit per URL for HTML or 5 for browser, with no additional Markdown charge.

## Plans

`credits` is the monthly pool (reset at the start of each UTC month, **no rollover**); `concurrency` caps running URL jobs across scrape, analyse and map, all user keys and API replicas. Jobs wait for capacity; each claim uses the current user plan. New accounts start on **free**.

| Plan | Price / mo | Monthly credits | Concurrency |
|---|---|---|---|
| `free` | $0 | 1,000 | 2 |
| `starter` | $49 | 25,000 | 5 |
| `growth` | $149 | 150,000 | 15 |
| `scale` | $499 | 750,000 | 40 |

Manage your subscription on the [billing](/billing) page. The same catalog is available programmatically at `GET /billing/plans`.

## Checking usage

`GET /usage` requires a signed-in Clerk user and returns the full current-period UsageCounter row. A first read initializes an empty counter without charging credits:

```ts
{
  userId: string;
  period: string; // UTC "YYYY-MM"
  creditsUsed: number;
  updatedAt: string; // JSON timestamp
}
```

`GET /me` returns the full User row: `id`, `email`, `plan`, `stripeCustomerId`, and `createdAt`. Read the plan catalog from `GET /billing/plans` and match the user's `plan` to derive credit and concurrency limits. Remaining credits are `Math.max(0, plan.credits - counter.creditsUsed)`.

These endpoints require user authentication; an API key does not grant account-wide access.

## Hitting a limit

| Status | Error code | Meaning |
|---|---|---|
| `402` | `QUOTA_EXCEEDED` | The request would exceed your monthly credits. |
| `503` | `CAPACITY_EXCEEDED` | The pending queue cannot admit the whole request. |

For `402`, `error.details` includes `creditsLimit`, `creditsUsed` and `creditsRemaining`. Upgrade your plan or wait for the next billing period.

For `503`, `error.details.retryAfterSeconds` is `5`, matching the `Retry-After: 5` header. Retry after that delay. Running-job plan caps schedule admitted work; they do not reject it with `429`.

Invocation failures use `{ "error": { "code", "message", "details" } }`. See [Errors and response contracts](/docs/api/errors) for exact shapes.

Markdown agents.txt

Each distinct URL admitted through a scrape endpoint or /analyse spends credits from the monthly pool tied to your plan. Plan concurrency caps running URL jobs across /scrape, /analyse and /map. Map uses the same scheduler and concurrency allowance but does not consume credits.

Credit cost per engine

Cost is charged per URL, keyed by the engine you request (a multi-URL request costs the sum).

Engine	Credits / URL
`html`	1
`json`	1
`analyse`	3
`browser`	5
`ai`	50

analyse is one fetch + one LLM pass. AI reserves 50 credits once for one queued job; internal HTML/JSON/browser calls do not reserve additional credits. AI shares browser capacity for its full run and also obeys its own concurrency cap and the user plan. Map is not metered. scrape_markdown uses the selected engine’s price: 1 credit per URL for HTML or 5 for browser, with no additional Markdown charge.

Plans

credits is the monthly pool (reset at the start of each UTC month, no rollover); concurrency caps running URL jobs across scrape, analyse and map, all user keys and API replicas. Jobs wait for capacity; each claim uses the current user plan. New accounts start on free.

Plan	Price / mo	Monthly credits	Concurrency
`free`	$0	1,000	2
`starter`	$49	25,000	5
`growth`	$149	150,000	15
`scale`	$499	750,000	40

Manage your subscription on the billing page. The same catalog is available programmatically at GET /billing/plans.

Checking usage

GET /usage requires a signed-in Clerk user and returns the full current-period UsageCounter row. A first read initializes an empty counter without charging credits:

{
  userId: string;
  period: string; // UTC "YYYY-MM"
  creditsUsed: number;
  updatedAt: string; // JSON timestamp
}

GET /me returns the full User row: id, email, plan, stripeCustomerId, and createdAt. Read the plan catalog from GET /billing/plans and match the user’s plan to derive credit and concurrency limits. Remaining credits are Math.max(0, plan.credits - counter.creditsUsed).

These endpoints require user authentication; an API key does not grant account-wide access.

Hitting a limit

Status	Error code	Meaning
`402`	`QUOTA_EXCEEDED`	The request would exceed your monthly credits.
`503`	`CAPACITY_EXCEEDED`	The pending queue cannot admit the whole request.

For 402, error.details includes creditsLimit, creditsUsed and creditsRemaining. Upgrade your plan or wait for the next billing period.

For 503, error.details.retryAfterSeconds is 5, matching the Retry-After: 5 header. Retry after that delay. Running-job plan caps schedule admitted work; they do not reject it with 429.

Invocation failures use { "error": { "code", "message", "details" } }. See Errors and response contracts for exact shapes.