Ephemeral

Cancel a run that has not finished. Work already done is billed. Cancelling a finished run changes nothing.

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

Start a saved workflow on a timetable. Needs an administrator key. Each start is a run billed to the organization, with the cost cap given here (or the default). Use preview_schedule first to check the timetable. A schedule pauses itself after repeated failed starts. An organization can have 50 schedules.

Permanently delete a schedule. Needs an administrator key. Runs it already started are not affected. To stop it for a while, pause it with update_schedule instead.

Permanently delete a saved workflow. Runs already started are not affected; schedules that use it stop being able to start runs until it is saved again.

Read a run: status, output, error, cost and billing_pending. COST: while billing_pending is true (or the run is still going), cost_micros is PROVISIONAL and usually higher than the final cost; the result then has cost_final:false and a cost_note. Quote a cost only when cost_final is true (the run is finished and billing_pending is false); otherwise call get_run again in a few seconds. For a zero-data-retention run the first read of a finished run returns the output and then deletes it. 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.

Read a schedule: timetable, time zone, input, cost cap, whether it is enabled, its next start and the outcome of its last start.

Read a saved workflow's definition: description, prompt, model, files, connections, limits and its input_schema and output_schema. Credentials are never included.

The organization's saved connections that a run may use, with type, allowed methods and tools. No URLs or secrets are returned. Reference one in create_run by name.

List the files saved in the organization: id, name, size, content type and creation time. Reference a file by id in a run's or workflow's files. Read-only; upload and delete files through the REST API.

Find models. Returns a compact list (id, name, context_length, input and output USD per million tokens, zero_data_retention where known), the total count and the default model. There are hundreds of models, so filter with query (case-insensitive part of the id or name, e.g. "claude", "gpt") and read the hint when the list is truncated (default 25, at most 100). Pass model for one model's full details. Use an id from it as create_run's model.

List the organization's runs, newest first, with a cursor for the next page. Each run has cost_final: when false, cost_micros is provisional (usually above the final cost) and billing is still settling.

List the organization's schedules: each starts a saved workflow on a cron timetable. Includes the next start, the last run and the last error.

List the organization's saved workflows (reusable run definitions). Each entry has the workflow's name and, when set, its description, input_schema (the shape of the input create_run expects) and output_schema (the shape of the JSON it returns), so you can call a workflow without reading its prompt. Run one with create_run and its name.

Check a cron expression and time zone and return the next five start times (UTC), without saving anything.

Start the schedule's workflow now, outside its timetable, with the schedule's input and cost cap. Returns the queued run (follow it with wait_for_run); each call starts another run and is billed like any run.

Create a workflow, or replace the one with this name (saving the same definition again changes nothing more). A workflow is a reusable run definition: start it with create_run and its name, or on a timetable with create_schedule. Connections must already be saved in the organization; reference them by name, never with a URL or a credential. Read the current definition with get_workflow first when you change part of it, because saving replaces the whole definition. Give it a description, and an input_schema and output_schema (JSON Schemas) so that agents can discover and call it: a run's input is checked against input_schema before it starts, and its output must be JSON matching output_schema or the run fails.

Change a schedule; only the fields you give change. Needs an administrator key. Set enabled to false to pause it and to true to resume it (resuming clears the failures that paused it). A new timetable counts from now.

Wait until a run finishes (succeeded, failed, cancelled, interrupted or timed_out) or the wait ends, then return the run. After the run finishes it keeps waiting, within the same time, until billing has settled (billing_pending false, normally a few seconds to about 20), so the cost is final. Waits at most 60 seconds; if the run is still going, the returned status says so and you can call it again. COST: if the result has cost_final:false, cost_micros is PROVISIONAL and usually higher than the final cost; do not quote it, call get_run again shortly. Quote the cost only when cost_final is true.