Concepts

Credits

A credit is held when a job starts, captured when it finishes, and released if it fails.

On this page

Hold, capture, release#

Writing an article costs credits, and the cost is settled in three moves:

Hold when the job starts. POST /articles answers with creditsHeld.
Capture when the job finishes. The job.done webhook carries the credits captured.
Release if the job fails or is cancelled. A refunded event ends the stream and job.failed carries refunded.

A job that writes language versions holds 1 credit more for each, and a version that is skipped, fails or comes back empty is released while the rest is captured: one refunded event with reason: "unused" carries the total, just before done, and does not end the stream. The primary article is never held back by a version. See Write in several languages.

A job that stays paused for an hour without being steered is failed and released. A model outage is waited out with backoff for up to 24 hours before the job gives up and releases.

What costs credits#

Action	Credits
A standard article (`length` short or standard)	1
A long article (`length` long)	2
Each language version, in a brief or added later	1 for each language, whatever the length
Creating or changing a brief, estimating, checking a topic	free
Adding a source, rewriting a paragraph, hand edits, structure edits	free
Regenerating an illustration	free, up to a daily limit
Exports and deliveries, reading a site again	free
A job that fails	released
A language version that is skipped, fails or comes back empty	released when the job finishes

A person’s first column on a site may be free. It is never free for a key or an agent.

Two rules about scopes#

Caps that stack#

A start can be refused by any of these layers, and the tightest one wins.

Layer	What happens
Workspace balance, or the trial having ended	402 `insufficient_credits`. For a key or an agent the message carries no numbers.
The key’s or agent’s daily cap	429 `budget_exhausted`, with `resetsAt` and `Retry-After`. Days are UTC; the cap resets at 00:00 UTC.
A Beat’s weekly budget	The Beat stops writing. Beats are managed by people.
The plan’s monthly limit for long articles	409 `plan_limit`.

A cap counts what the credential held today minus what it released. It can be raised by the person who created it, in Developer.

Credits are never shown to a key or an agent#

The balance is not in any response a credential can read. POST /briefs/{id}/estimate returns enough: true or false, and a refused start returns a generic 402. The check is whether the trial is still running, the balance covers the cost, and today’s spend plus the cost fits the credential’s cap.