SuperCoolDocs Get an API key
Menu

Guides

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.

View as Markdown

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.

#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 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

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. 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

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 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.

Last updated