---
title: "Ask the agent"
description: "Start one agent run without a browser. The agent plans, calls tools, and can start paid generations on its own up to the cap you set.\n\nTwo caps govern the run and neither replaces the other. `max_credits` bounds what the run's own thinking may cost. `generation_spend_cap_credits` bounds what the run may spend on renders, voices and other paid work without asking a person — it defaults to 0, so a run you say nothing about can never charge you for a render. Both caps are bounded again by this API key's own spend policy, and the policy always wins.\n\nSend `quote_only: true` to see the ceiling for free; the ceiling is `max_credits + generation_spend_cap_credits`. Send the same body with the returned `quote_id` to run it. Confirming reserves the ceiling, and the unused part is refunded when the run ends, so you are never charged more than the number you saw.\n\nThe run is asynchronous: read it at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits as a card in `pending_approvals`; approve it in roasOS, or decline it here."
url: https://docs.roasos.com/api-reference/agent/createAgentCompletion
---

# Ask the agent

Start one agent run without a browser. The agent plans, calls tools, and can start paid generations on its own up to the cap you set.

Two caps govern the run and neither replaces the other. `max_credits` bounds what the run's own thinking may cost. `generation_spend_cap_credits` bounds what the run may spend on renders, voices and other paid work without asking a person — it defaults to 0, so a run you say nothing about can never charge you for a render. Both caps are bounded again by this API key's own spend policy, and the policy always wins.

Send `quote_only: true` to see the ceiling for free; the ceiling is `max_credits + generation_spend_cap_credits`. Send the same body with the returned `quote_id` to run it. Confirming reserves the ceiling, and the unused part is refunded when the run ends, so you are never charged more than the number you saw.

The run is asynchronous: read it at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits as a card in `pending_approvals`; approve it in roasOS, or decline it here.

## `POST /v1/agent/completions`

Endpoint: `POST https://api.roasos.com/v1/agent/completions`

Ask the agent

Start one agent run without a browser. The agent plans, calls tools, and can start paid generations on its own up to the cap you set.

Two caps govern the run and neither replaces the other. `max_credits` bounds what the run's own thinking may cost. `generation_spend_cap_credits` bounds what the run may spend on renders, voices and other paid work without asking a person — it defaults to 0, so a run you say nothing about can never charge you for a render. Both caps are bounded again by this API key's own spend policy, and the policy always wins.

Send `quote_only: true` to see the ceiling for free; the ceiling is `max_credits + generation_spend_cap_credits`. Send the same body with the returned `quote_id` to run it. Confirming reserves the ceiling, and the unused part is refunded when the run ends, so you are never charged more than the number you saw.

The run is asynchronous: read it at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits as a card in `pending_approvals`; approve it in roasOS, or decline it here.

### Parameters

- `undefined`
- `undefined`
- `undefined`

### Request body

Content type: `application/json`

### Responses

- `200`: A ceiling quote. Nothing is reserved and nothing runs.
- `202`: Run accepted. Poll /v1/agent-runs/{id}/status.
- `400`: validation_error, quote_required, a missing Idempotency-Key, or spend_cap_exceeds_policy
- `402`: insufficient_credits, or approval_required when a cap exceeds this key's unattended limit
- `403`: The API key is not authorized to start agent runs
- `409`: The idempotency key was reused with different request data
- `410`: quote_expired: the quote must be replaced under a new idempotency key
- `429`: rate_limit_exceeded, or a daily or monthly credit budget
- `503`: The run could not be recorded or started safely

Read the full reference at https://docs.roasos.com/api-reference/agent/createAgentCompletion.