Create a run
create_runStart an AI agent run in an isolated sandbox and return the run (status queued) at once. Give a prompt, or the name of a saved workflow. Poll with get_run or block with wait_for_run for the result. Every run has a cost cap (max_cost_micros) and a timeout, and is billed to the organization of the API key. Connections must already be saved in the organization; reference them by name. Use idempotency_key to make a retry safe. A run's cost_micros is provisional (usually above the final cost) until cost_final is true; see get_run. On the hosted service a run costs a run fee once its worker starts, compute per second, model calls at the provider's price plus a percentage, and web requests and searches at flat prices; GET /v1/me reports the rates.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| web | No | Web access: true, false, or an object limiting it. | |
| files | No | Files placed in the sandbox: inline content, or a file saved in the organization. | |
| input | No | Any JSON the agent receives as its input. If the workflow has an input_schema, it must match. | |
| model | No | A model id from list_models. Omit for the default. | |
| shell | No | Whether the agent may run shell commands in its sandbox. | |
| prompt | No | What the agent should do. Required unless workflow is set. | |
| workflow | No | Name of a saved workflow to run instead of a prompt (see list_workflows). | |
| connections | No | Saved connections the agent may use, keyed by the name the agent sees. Each refers to a connection saved in the organization and can only narrow it. | |
| description | No | What the workflow does and what input it expects, in a sentence or two, for people and agents. At most 500 characters. | |
| input_schema | No | A JSON Schema (draft 2020-12 or 7, at most 32 KiB, no references to other documents) that this run's input must match. A run whose input does not match is refused with the path and the reason, such as "input.city: required". | |
| output_schema | No | A JSON Schema (draft 2020-12 or 7, at most 32 KiB, no references to other documents) that this run's output must match. The agent is told the schema and asked to reply with JSON only; the output is then checked, and a run whose output does not match fails with the reason. | |
| idempotency_key | No | A retry with the same key returns the original run instead of starting another. | |
| max_cost_micros | No | Cost cap in millionths of a dollar. The run stops at the cap. | |
| timeout_seconds | No | Wall-clock limit for the run. | |
| zero_data_retention | No | Record nothing of the run's content; the output is kept only briefly and released on first retrieval. |