# Credits & pricing

> The SuperCool API uses the same credits as the app. Talking to the agent is free; credits are used when it starts work. What happens when you run out.

Source: https://supercool.com/docs/api/credits

There's no separate API price list. The API uses the same credits as the SuperCool app, from the same balance, on any plan.

- **Talking to the agent is free.** Questions, answers and planning cost nothing.
- **Credits are used when the agent starts work**: making a video, generating images, building a site, running research. What a job costs depends on the work, just as it does in the app.
- See plans and credit packs on the [pricing page](https://supercool.com/pricing).

## See what you spend

- **Your balance:** `GET /v1/me` returns `credits`, the credits available now.
- **Per message:** every message has `credits_used`, the credits its jobs have used so far. It grows while work runs and is final when the message is.
- **Per key:** the [API dashboard](https://supercool.com/dashboard#api) shows requests and credits for each API key. Credits are counted per job, so usage stays accurate even when the app, the CLI and several keys all work in the same chat.

```bash
curl https://api.supercool.com/v1/me -H "Authorization: Bearer $SUPERCOOL_API_KEY"
# { "object": "account", "plan": "pro", "credits": 1840, ... }
```

## Running out of credits {#out-of-credits}

Running out is **not an HTTP error**. The message is accepted (`201`), and its status tells you what happened. It shows up as `"status": "blocked"` (or `partial`, if some work did finish) with `"reason": "out_of_credits"`, and triggers the `message.blocked` and `job.blocked` [webhooks](https://supercool.com/docs/api/webhooks). What to do depends on when the credits ran out:

### Before the work was queued

The agent couldn't start the work. The message has a refused job (`job_id` starting with `ref_`, `kind: "refusal"`, `final: true`), and nothing more will happen.

**What to do:** add credits, then send the message again.

### Queued, waiting for credits {#queued}

The work was queued but couldn't start. The job keeps its real `exe_…` id with `queued: true` and `final: false`, and the message says how to resume it:

```json
{
  "status": "blocked",
  "reason": "out_of_credits",
  "final": false,
  "resume": "add_credits",
  "resume_by": "2026-10-01T14:02:11.402000Z",
  "jobs": [{ "job_id": "exe_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e", "status": "blocked", "reason": "out_of_credits", "queued": true, "final": false, "resume_by": "2026-10-01T14:02:11.402000Z" }]
}
```

**What to do:** add credits before `resume_by` (24 hours after it was queued). The work **starts by itself**: you get `job.resumed`, then the result. **Don't resend the message**, or the work runs twice. After `resume_by` the job becomes `expired` with `reason: "queue_expired"` and you need to send the message again. That rule is deliberate: nobody gets charged for a day-old request they may have forgotten.

### Mid-run

The work started and ran out of credits partway. The job ends `blocked` with `out_of_credits` and `final: true`, and the chat's [work status](https://supercool.com/docs/api/work) is `stalled_credits`.

**What to do:** add credits, then send a follow-up like "continue the candle ad". The agent picks up in the same chat.

## Adding credits

Buy credits or upgrade your plan in the SuperCool app, or turn on pay-as-you-go top-ups so work doesn't stop when your balance runs low. Whenever credits land (a purchase, a top-up, a plan renewal), queued API work that is waiting for them resumes on its own.

## Hosting fees

If hosting fees for your SuperCool sites are due, new work is refused with `reason: "hosting_fees"`. Settle them in the app, then send the message again.