# Credits and limits

> What every action costs, when credits are refunded, how to quote a call with dry_run, and the request and size limits.

Credits are the hard limit on spend. Every action that costs credits is quoted before it runs, a job that does not fit the balance is refused with `402 insufficient_credits` and nothing is charged, and credits charged for work that could not run are refunded. The request and size limits below only stop one key from flooding the system.

The balance is `credits.remaining` in `GET /workspace` (MCP: `get_workspace`). The first workspace you create with `create_workspace` starts with 250 credits; every later one starts at 0. Plans add a monthly allowance:

| Plan | Credits per month | Trial credits |
|---|---|---|
| Starter | 5,000 | 1,000 |
| Growth | 8,000 | 2,000 |
| Agency | 22,000 | None; starts on a call |

More on [pricing](https://neuropage.io/pricing), including top-ups.

## What each action costs

| Action | API or tool | Credits | Refunded when | `dry_run` |
|---|---|---|---|---|
| Page for a new lead | `POST /jobs`, `generate_assets` | 3 (1 analysis + 2 page), the `cost_per_asset` ceiling, plus any research columns the campaign runs on new leads | The page cannot start (before the answer), the lead fails later, or the job was accepted but never started | Yes |
| Page for a lead whose profile was already read | `POST /jobs`, `generate_assets` | 2 | The page cannot start (before the answer), the lead fails later, or the job was accepted but never started | Yes |
| Page that already exists in the campaign (`reused: true`) | `POST /jobs`, `generate_assets` | 0 | Nothing was charged | Yes |
| Lead analysis on import | `import_leads` | 1 per new lead whose profile was not read before | The analysis cannot start | Yes |
| Lead analysis on an Instantly import | `import_from_instantly` | Up to 1 per new lead analysed, at most `limit` leads; nothing for a campaign that is not active or needs no LinkedIn URL | - | Yes |
| Page generation for a campaign | `generate_pages` | 2 per page | The run cannot start | Yes |
| Messages (emails and LinkedIn) | `generate_messages` | 0.5 per lead, whatever the channels | The run cannot start | Yes |
| Research column | `run_research` | Per lead and column; the price is `credits_per_lead` on each column in `list_columns` | A column that finds nothing | Yes |

A dash in "Refunded when" means no refund is documented for that action. A refunded page shows in `refunded`, `credits_refunded` and `refund_message` on `GET /jobs/{id}`.

**Free:** every read (`list_*`, `get_*`, `check_variables`), and every write to a brand, template, media, campaign, column, cell, message setting, Instantly send or event subscription (`create_campaign` takes `dry_run` too, and spends nothing). `set_cell_values` and `set_messages` are free.

**In the app.** These are charged by the NeuroPage app, not by the API or MCP: a test send of a sequence email costs 1 credit, and a lead's mobile number costs 20 credits, charged only when a number is found and only if you turned on phone lookup in the Telegram integration.

## Limits

| Limit | Value | Error | Sandbox key |
|---|---|---|---|
| Requests per key, or per signed-in user | 60 per minute | `429`, `limit: requests` | 10 per minute |
| Leads per job (`POST /jobs`, `generate_assets`) | 25 | `422 too_many_leads` | 25 |
| Running page jobs per workspace | 2 | `429`, `limit: running_jobs` | 1 |
| New pages per workspace per hour | 200 | `429`, `limit: assets_hour` | 10 (the day cap) |
| New pages per workspace per day | 1,000 | `429`, `limit: assets_day` | 10 |
| Leads per `import_leads` call | 500 | `422 validation_failed` | 500 |
| `create_workspace` per user per day | 3 | `429`, `limit: workspaces_day` | Not available |
| Credits per key per month | The key's monthly cap, if you set one; resets on the 1st (UTC) | `402 spend_cap_reached` | 30 |

Every `429` has a `Retry-After` header, and responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. A job that only reuses existing pages starts nothing and counts against none of the page limits. A sandbox key is for trying the API on a shared demo workspace. [Contact us for sandbox access](https://neuropage.io/contact); see [Sandbox and plans](https://docs.neuropage.io/sandbox-and-plans).

## Worked example: 25 new leads, pages and messages

A new lead costs 1 analysis plus 2 page credits, which is the 3 in `cost_per_asset`. This campaign has no research columns.

| Step | Calculation | Credits |
|---|---|---|
| Pages for 25 new leads | 25 × (1 + 2) | 75 |
| Messages for 25 leads | 25 × 0.5 | 12.5 |
| **Total** | | **87.5** |

Send the same 25 LinkedIn URLs to the same campaign again and every page comes back `reused: true` for 0 credits. If the profiles were already read in another campaign, the pages cost only the 2 page credits each: 50 in all. Regenerating messages charges 0.5 credits a lead again.

## Quote first

Add `dry_run: true` to `POST /jobs`, or to any spending tool over MCP (`generate_assets`, `import_leads`, `import_from_instantly`, `generate_pages`, `generate_messages`, `run_research`). It answers with the most the call can cost and your balance, and changes nothing. For `POST /jobs` the answer is a `JobQuote`: `credits_quoted`, `leads_accepted`, `leads_reused`, `leads_rejected`, `credits_remaining` and `enough_credits`.

```bash
curl -X POST https://neuropage.io/api/v1/jobs \
  -H "Authorization: Bearer np_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "landing_page", "dry_run": true, "leads": [{ "linkedin_url": "https://www.linkedin.com/in/jane-doe" }]}'
```

If the balance is too low, a real call returns `402 insufficient_credits` and nothing is charged; `402 spend_cap_reached` means the key's monthly cap would be passed. See [Errors](https://docs.neuropage.io/errors) and [Concepts](https://docs.neuropage.io/concepts), and the [MCP tools](https://docs.neuropage.io/mcp) for the same table per tool.
