Quotes and credits

Every paid action in roasOS obeys one rule. You see the price before roasOS charges you.

The quote and confirm flow

A paid request has two steps.

1. Quote. Set quote_only to true. roasOS calculates the price, and it charges nothing.
2. Confirm. Send the same body again with the quote_id of that quote. Only this step uses credits.

A quote returns 200:

{
  "data": {
    "kind": "quote",
    "quote_id": "8c4a1f77-...",
    "credits": 9,
    "expires_at": "2026-08-19T10:14:11Z",
    "pricing_version": "customer-pricing@2026-10-30.v14",
    "authorization": { "status": "auto_approved" },
    "confirmation": {
      "model": "kling-4",
      "mode": "image-to-video",
      "duration_seconds": 5,
      "generate_audio": true
    }
  }
}

Read confirmation. It states what roasOS understood from your request. The price is for that reading, not for the words that you sent.

A confirm returns 201 with a job, an analysis or an agent run. Refer to Jobs.

Send quote_only and quote_id in one body, and roasOS answers 400. The message is quote_id must be omitted when quote_only is true.

Idempotency keys

A paid request needs an Idempotency-Key header. The value is 16 to 255 characters. Use letters, numbers, and the characters ., _, : and -. A value in another shape is a 400 invalid_idempotency_key, and an absent header is a 400 idempotency_key_required.

The key makes a second attempt safe. Send the same request twice with the same key, and roasOS gives you the same result. roasOS charges you one time only.

Use the same key for a quote and for its confirm.

-H "Idempotency-Key: order-12345-image-1"

Quotes have a time limit

A quote is valid for 10 minutes. After 10 minutes a confirm answers 410 quote_expired. Quote the request again, with a new Idempotency-Key.

A quote applies only to the request that you priced. You cannot change the prompt or the model between the quote and the confirm. A changed body gets a new quote.

The endpoints that never quote

A free endpoint costs 0 credits. It needs no Idempotency-Key, it refuses quote_only, and it never answers with a quote. Do not write a quote step for one of these calls.

Every read and every delete is free. These writes are free as well:

• POST /v1/products and POST /v1/uploads
• POST /v1/memory/pins
• PUT /v1/brand-kit and PUT /v1/memory/brief
• POST /v1/intelligence/refresh
• POST /v1/agent-runs/{id}/gates/{gate_id}/decline
• POST /v1/agent-runs/{id}/cancel and POST /v1/jobs/{id}/cancel

Two endpoints are exceptions to the rule above.

• POST /v1/agent-runs/{id}/gates/{gate_id}/approve costs 0 credits and needs an Idempotency-Key. The approval starts the follow-up run that renders the approved card, and that run spends on your key. It answers with no quote. Refer to Agent runs.
• POST /v1/generation-batches/quotes answers with a quote and nothing else, and it never charges. Refer to Overview.

Reserved credits and charged credits

• At the confirm step, roasOS reserves the credits. The job envelope reports them in credits_reserved.
• If the action is successful, roasOS captures the reservation and charges you.
• If the action fails, roasOS releases the reservation and charges you nothing. A provider error and a timeout are two causes of a failure.

To read your balance, send GET /v1/account:

{
  "credits": {
    "available": 1570,
    "reserved": 0,
    "pending_refunds": 0
  }
}

What an agent run costs

An agent run has a second price axis. A run spends on two things: its own thinking, and the renders that it starts.

Two caps govern one run, and neither replaces the other.

Each cap stops at 100,000 credits. The key spend policy can lower either default. The generation cap defaults to 0 on purpose. A run that you say nothing about never charges you for a render. It opens a gate, and it waits for your approval.

quote_only: true on an agent run answers with the ceiling, which is max_credits plus generation_spend_cap_credits. roasOS does not predict what the run will do. The confirm reserves that whole ceiling.

roasOS then meters the run on the tokens that it used. A run prices at agent-token-pricing@2026-10-04.v3, and a model endpoint prices at customer-pricing@2026-10-30.v14. At the end of the run roasOS charges the metered cost, and it refunds the rest of the ceiling. A run on a model with no published rate charges 0 credits and refunds in full.

Refer to Agent runs.

The approval threshold

Each API key carries a spend policy. It holds the price of one call, two budgets, an approval threshold, and the models the key may call. Send GET /v1/limits to read it. Refer to Cost controls for the whole response.

A quote reports the decision of that policy in authorization.status.

• auto_approved — the price is at or under policy.approval_threshold_credits. Confirm the quote.
• approval_required — the price is above it. The quote carries an authorize_url. Approve the request at that URL, then confirm the quote.

roasOS refuses a request that is over a bound, and the code names the bound: 403 request_credit_limit_exceeded, 403 daily_credit_budget_exceeded, 403 monthly_credit_budget_exceeded or 403 spend_approval_required. Refer to Errors.

The same threshold governs an unattended agent run. The agent pages name it auto_approve_up_to_credits, and it is the same policy value.

Read your usage

• GET /v1/account/usage gives a list of the charges.
• GET /v1/account/ledger gives the full billing record with reservations and refunds.
• GET /v1/account/usage/summary gives the totals for each day.

The list of charges and the ledger are paged. The summary is not. Refer to Pagination.