Runs · Ephemeral docs

Start runs, follow them and read their results. Every endpoint on this page works with member and admin keys. See runs for the lifecycle and limits.

Start a run

POST/v1/runs

Creates a run and queues it. Send either a prompt or the name of a saved workflow.

Body

promptstring

The task. Required unless workflow is set; with a workflow, it replaces the saved prompt. Up to 128 KiB.

inputany JSON

Data for the task, passed to the agent as JSON. Up to 1 MiB.

workflowstring

Name of a saved workflow. Other definition fields you send override the saved ones.

modelstring

Model ID. Defaults to default_model from GET /v1/models.

filesarray

Up to 32 entries, each {"file": "<id or name>", "path": "..."} or {"path": "...", "content": "..."}. See files.

connectionsobject

Up to 16 connections, keyed by the name the agent sees. Each is {"ref": "<saved name>"} with optional allowed_methods or allowed_tools, or an inline definition. See connections.

descriptionstring

What the run does, for people and agents. Up to 500 characters. Harmless on an inline run; with a workflow it replaces the saved description.

input_schemaobject

A JSON Schema that input must match; a mismatch returns 400 with the path and reason, such as input.city: required. With a workflow, it replaces the saved schema. See describing inputs and outputs.

output_schemaobject

A JSON Schema that the run's output must match; a mismatch ends the run failed. With a workflow, it replaces the saved schema. See describing inputs and outputs.

timeout_secondsinteger

1 to 3600. Default 300.

shellboolean

Lets the agent run shell commands and write files in its working directory. Default true.

webboolean | object

Lets the agent fetch pages, call public APIs and search through Ephemeral. true, or { "allow": [domains], "search": false } to limit it. Default off. See web access.

zero_data_retentionboolean

Records nothing of the run's content: no stored events, no definition, and an output that is returned once. Hosted runs cost more. See zero data retention. Default false.

max_cost_microsinteger

Budget, 1 to 100,000,000. Defaults to default_max_cost_micros from GET /v1/me. On the hosted service it must cover the compute charge for the full timeout. See budgets.

callbackobject

{"url": "...", "secret": "..."} for a signed request when the run ends. See callbacks.

Headers

Idempotency-Keystring

Optional, up to 200 characters. A repeated key returns the existing run with 200.

Terminal

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d0f3c1e-6a52-4b8e-9f21-0c4d5e6a7b89" \
  -d '{
    "workflow": "investigate-payment",
    "input": { "payment_id": "pay_123" },
    "max_cost_micros": 500000
  }'

The response is 202 Accepted with the new run object. A request that fails validation returns 400 and creates nothing. On the hosted service, 402 means your available credits do not cover the budget.

The run object

idstring

Run ID, such as run_4abb0f420c6623a12d2889610eb67284.

statusstring

reserving, queued, starting, running, succeeded, failed, cancelled, timed_out or interrupted.

outputstring

The agent's final answer. Omitted until there is one. Up to 1 MiB; a longer answer is cut there and an output_truncated event says so.

errorstring

Why the run did not succeed. Omitted when empty.

created_attimestamp

When the run was created.

started_attimestamp

When it left the queue. Omitted before that.

finished_attimestamp

When it reached a final status. Omitted before that.

max_cost_microsinteger

The run's budget.

cost_microsinteger

Cost so far. Provisional until billing_pending is false on a finished run. Omitted when zero.

billing_pendingboolean

Whether the cost still has to be settled.

schedule_idstring

The schedule that started the run, when one did.

zero_data_retentionboolean

true for a zero-data-retention run.

surcharge_percentinteger

The surcharge rate, for zero-data-retention runs on the hosted service.

surcharge_microsinteger

The part of cost_micros added by the zero-data-retention surcharge. Omitted when zero.

output_availableboolean

Zero-data-retention runs only: whether the output is still held for retrieval.

output_expires_attimestamp

Zero-data-retention runs only: when a held output is deleted if nobody has read it.

JSON

{
  "id": "run_4abb0f420c6623a12d2889610eb67284",
  "status": "succeeded",
  "output": "The card issuer declined pay_123 for insufficient funds. The processor had no incidents. Ask the customer to retry or use another card.",
  "created_at": "2026-10-03T09:14:05.118Z",
  "started_at": "2026-10-03T09:14:05.402Z",
  "finished_at": "2026-10-03T09:14:41.877Z",
  "max_cost_micros": 500000,
  "cost_micros": 14390,
  "billing_pending": false
}

List runs

GET/v1/runs

Returns runs, newest first.

Query

limitinteger

1 to 100. Turns on paginated responses.

cursorstring

The next_cursor from the previous page.

statusstring

Return only runs with this status.

schedulestring

Return only runs started by this schedule.

GET /v1/runs?limit=2&status=failed

{
  "items": [
    { "id": "run_91c0…", "status": "failed", "error": "Worker failed; inspect run events. External actions may have completed.", "created_at": "2026-10-03T08:51:12.004Z", "max_cost_micros": 500000, "cost_micros": 61200, "billing_pending": false },
    { "id": "run_3fd2…", "status": "failed", "error": "Credit reservation failed", "created_at": "2026-10-02T17:20:44.390Z", "max_cost_micros": 500000, "billing_pending": false }
  ],
  "next_cursor": "eyJvIjoib3JnXzVlMmIi…"
}

Without limit or cursor, the response is a plain array of the 100 most recent matching runs. See pagination.

Get a run

GET/v1/runs/{id}

Returns the run object. Poll this until the status is final, or use events or a callback.

Stream events

GET/v1/runs/{id}/events

A server-sent event stream. It replays every recorded event, then sends new ones as they happen. When the run is final it sends done with the run object and closes.

Headers

Last-Event-IDinteger

Resume after this event ID, for example when reconnecting after a dropped connection.

Text

: connected

id: 88412
event: status
data: {"id":88412,"type":"status","data":{"status":"running"},"created_at":"2026-10-03T09:14:05.431Z"}

id: 88415
event: worker_started
data: {"id":88415,"type":"worker_started","data":{"runtime":"pi","mode":"pi","shell":false},"created_at":"2026-10-03T09:14:07.906Z"}

id: 88419
event: tool_start
data: {"id":88419,"type":"tool_start","data":{"tool":"http_0","id":"call_1","arguments":{"method":"GET","path":"/payments/pay_123"}},"created_at":"2026-10-03T09:14:10.215Z"}

id: 88431
event: result
data: {"id":88431,"type":"result","data":{"output":"The card issuer declined pay_123 for insufficient funds."},"created_at":"2026-10-03T09:14:41.702Z"}

event: done
data: {"id":"run_4abb0f420c6623a12d2889610eb67284","status":"succeeded", …}

Each message's data is an event object with id, type, data and created_at, except done, which carries the run object. Lines starting with a colon are comments; a heartbeat comment is sent every 15 seconds. The event types are listed under event types. Disconnecting does not cancel the run.

Terminal

curl -N $EPHEMERAL_URL/v1/runs/run_4abb0f420c6623a12d2889610eb67284/events \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY"

Cancel a run

POST/v1/runs/{id}/cancel

Cancels a run that is reserving, queued, starting or running, and returns the run object. A run that has already finished is returned unchanged.

Cancelling stops the worker. It does not undo anything the agent already did through a connection.

Read a run definition

GET/v1/runs/{id}/definition

Returns the definition the run actually used, prepared for review before running it again.

JSON

{
  "request": {
    "prompt": "Find out why this payment failed. Follow the playbook.",
    "model": "anthropic/claude-haiku-5.5",
    "files": [{ "file": "file_9c41d2a07be35f1e8a6c0d4b9e2f7a13", "path": "playbook.md" }],
    "connections": {
      "payments": { "ref": "payments-api", "allowed_methods": ["GET"] },
      "crm": { "type": "http", "url": "https://api.example.com", "allowed_methods": ["GET"] }
    },
    "timeout_seconds": 120,
    "shell": false,
    "max_cost_micros": 500000,
    "input": { "payment_id": "pay_123" }
  },
  "requires_credentials": ["crm"]
}

request is the resolved definition. File names are replaced by the IDs that were used, and a workflow's saved fields are filled in. The workflow name and callback are left out. Saved connections keep only their reference and allowlists. Inline connections lose their credentials and any secrets in their URL.

requires_credentials lists inline connections that need credentials or their original URL restored. To run it again, add those back, choose a new max_cost_micros, and send the request to POST /v1/runs. Saved connection references are resolved again at that point, and the request fails if a referenced file or connection has been deleted.

The definition keeps your prompt, input and inline file contents as sent. Do not place secrets in them.

Zero data retention runs

A run with zero_data_retention returns its output once. The first GET /v1/runs/{id} after it finishes includes output and deletes it; later reads omit it and report output_available: false. When the run has a callback, the callback delivers the output, and GET leaves it in place until then. An undelivered output is deleted after at most an hour.

The event stream works while the run works and for a few minutes afterwards. GET /v1/runs/{id}/definition returns 410, and run lists never include output. On the hosted service cost_micros includes the surcharge, and the budget must cover it.