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

# Credits and limits

> What a call costs, how many you can make, how many generations can run at once, and the ceilings on prompts and generation time.

The REST API and the MCP server draw on the same workspace, so everything here applies to both. They share one credit balance and one generation limit; they don't get one each.

## Credits

**One credit per generation.** There's no separate API quota. Calls spend from the same balance as the app, so an email generated from code costs exactly what one generated in the editor costs.

Over MCP, three more tools cost a credit each: `edit_email`, `import_email_from_html`, and `import_esp_template`. Every other tool is free. See [Tools](https://docs.alpacarelay.com/developers/mcp/tools.md#what-costs-credits).

The credit is taken when generation **starts**, and given back if the AI generation itself fails. In practice:

| Outcome | Credit |
| - | - |
| Success | Spent |
| `no_credits` | Nothing was taken |
| `generation_failed` | Usually refunded. Kept only when the email was already saved and a later step failed |
| `timed_out` | Kept. The generation usually goes on to finish and save the email in your workspace |
| Your client disconnects or times out | Kept. The email still finishes and is saved in your workspace |

> [!TIP]
>
> After a `timed_out`, or after your own client gave up, check **Emails** in the app (or `list_emails` over MCP) before retrying. The email you paid for is often already there.

Running out returns `no_credits`. On the REST API it arrives as a terminal `error` event on the stream, because the balance is checked once generation is already under way.

Top up or change plan under **Settings** → **Billing & usage**.

## Call budget

**60 calls a minute.** Every REST request and every MCP tool call spends one, whether or not it costs a credit. Listing an MCP server's tools when your client connects spends nothing.

| Connected with | Budget counted per |
| - | - |
| API key | Key |
| OAuth sign-in | Your user account, shared by every client you've approved, in every workspace |

Going over returns `rate_limited`, with HTTP 429 on REST. Over MCP the message says how many seconds to wait. Slow down rather than retrying straight away.

## Concurrency

**Three generations at once per workspace.** A fourth is rejected immediately with `rate_limited`, before the stream opens. Over MCP, only `generate_email` counts. `edit_email` and the other AI tools don't take a slot.

The limit is per *workspace*, counted across every key and every sign-in:

> [!NOTE]
>
> Extra API keys don't buy extra generation throughput. Each key gets its own call budget, but the three-generation limit counts across all of a workspace's keys, so a second key can't be used to multiply burst capacity.

For bulk generation, run a queue with three workers rather than firing everything at once and retrying the rejections. At one to three minutes per generation, three workers stay far below the call budget.

Handle `rate_limited` by retrying with a short backoff. It means "too many right now", not "stop". A generation finishing frees a slot within minutes.

## Prompt length

`prompt` is capped at **4000 characters** on the REST API. Over that returns `prompt_too_long` with a 400, before anything is charged.

That's a lot of room, far more than a good prompt usually needs. If you're near it, you're probably pasting content that belongs in the email instead of describing what the email should be.

## Generation time

| | |
| - | - |
| Typical | 1–3 minutes |
| Keep-alive | every \~15 seconds (REST), every \~10 seconds (MCP) |
| Server backstop | a little over 5 minutes |

Generation is slow enough that it belongs in a background job, not in a request a user is waiting on.

If the backstop fires you get a terminal `timed_out` error. It's rare, and it means something in the pipeline stalled, not that your prompt was too ambitious.

> [!TIP]
>
> Set your client timeout to at least **six minutes**, comfortably past the server's own deadline. Then a timeout on your side means something is genuinely wrong, not that you gave up early on a generation you've already paid for.

## Summary

| Limit | Value | Exceeded |
| - | - | - |
| Cost | 1 credit per generation or AI edit | `no_credits` |
| Call budget | 60 a minute per key, or per user with OAuth | `rate_limited` |
| Concurrency | 3 generations per workspace, all keys and sign-ins | `rate_limited` |
| Prompt | 4000 characters | `prompt_too_long` |
| Generation time | backstop just over 5 min | `timed_out` |


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