Ejecuciones · Documentación de Ephemeral

Inicia ejecuciones, síguelas y lee sus resultados. Todos los endpoints de esta página funcionan con claves de miembro y de administrador. Consulta ejecuciones para conocer el ciclo de vida y los límites.

Iniciar una ejecución

POST/v1/runs

Crea una ejecución y la pone en cola. Envía un prompt o el nombre de un workflow guardado.

Cuerpo

promptstring

La tarea. Obligatorio salvo que se indique workflow; con un flujo de trabajo, reemplaza al prompt guardado. Hasta 128 KiB.

inputany JSON

Datos para la tarea, que se pasan al agente como JSON. Hasta 1 MiB.

workflowstring

Nombre de un flujo de trabajo guardado. Los demás campos de definición que envíes sustituyen a los guardados.

modelstring

ID del modelo. Por defecto, default_model de GET /v1/models.

filesarray

Hasta 32 entradas, cada una {"file": "<id or name>", "path": "..."} o {"path": "...", "content": "..."}. Consulta archivos.

connectionsobject

Hasta 16 conexiones, indexadas por el nombre que ve el agente. Cada una es {"ref": "<saved name>"} con allowed_methods o allowed_tools opcionales, o una definición en línea. Consulta conexiones.

descriptionstring

Qué hace la ejecución, para personas y agentes. Hasta 500 caracteres. Es inocua en una ejecución en línea; con un flujo de trabajo reemplaza la descripción guardada.

input_schemaobject

Un JSON Schema al que debe ajustarse input; si no coincide, se devuelve 400 con la ruta y el motivo, por ejemplo input.city: required. Con un flujo de trabajo, reemplaza el esquema guardado. Consulta describir la entrada y la salida.

output_schemaobject

Un JSON Schema al que debe ajustarse la salida de la ejecución; si no coincide, la ejecución termina en failed. Con un flujo de trabajo, reemplaza el esquema guardado. Consulta describir la entrada y la salida.

timeout_secondsinteger

De 1 a 3600. Por defecto 300.

shellboolean

Permite que el agente ejecute comandos de shell y escriba archivos en su directorio de trabajo. Por defecto true.

webboolean | object

Permite que el agente obtenga páginas, llame a API públicas y busque a través de Ephemeral. true, o { "allow": [domains], "search": false } para limitarlo. Desactivado por defecto. Consulta acceso web.

zero_data_retentionboolean

No registra nada del contenido de la ejecución: ni eventos guardados, ni definición, y la salida se devuelve una sola vez. Las ejecuciones alojadas cuestan más. Consulta retención cero de datos. Por defecto es false.

max_cost_microsinteger

Presupuesto, de 1 a 100000000. Por defecto, default_max_cost_micros de GET /v1/me. En el servicio alojado debe cubrir el cargo de cómputo del tiempo límite completo. Consulta presupuestos.

callbackobject

{"url": "...", "secret": "..."} para recibir una solicitud firmada cuando termine la ejecución. Consulta callbacks.

Cabeceras

Idempotency-Keystring

Opcional, de hasta 200 caracteres. Una clave repetida devuelve la ejecución existente con 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
  }'

La respuesta es 202 Accepted con el nuevo objeto de ejecución. Una solicitud que no pasa la validación devuelve 400 y no crea nada. En el servicio alojado, 402 significa que tus créditos disponibles no cubren el presupuesto.

El objeto de ejecución

idstring

ID de la ejecución, como run_4abb0f420c6623a12d2889610eb67284.

statusstring

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

outputstring

La respuesta final del agente. Se omite hasta que exista. Hasta 1 MiB; una respuesta más larga se corta ahí y un evento output_truncated lo indica.

errorstring

Por qué la ejecución no tuvo éxito. Se omite cuando está vacío.

created_attimestamp

Cuándo se creó la ejecución.

started_attimestamp

Cuándo salió de la cola. Se omite antes de eso.

finished_attimestamp

Cuándo alcanzó un estado final. Se omite antes de eso.

max_cost_microsinteger

El presupuesto de la ejecución.

cost_microsinteger

Coste hasta el momento. Provisional hasta que billing_pending sea false en una ejecución terminada. Se omite cuando es cero.

billing_pendingboolean

Si el coste todavía debe liquidarse.

schedule_idstring

La programación que inició la ejecución, cuando fue una.

zero_data_retentionboolean

true en una ejecución con retención cero de datos.

surcharge_percentinteger

La tasa del recargo en ejecuciones con retención cero de datos del servicio alojado.

surcharge_microsinteger

La parte de cost_micros que añade el recargo de retención cero de datos. Se omite si es cero.

output_availableboolean

Solo en ejecuciones con retención cero de datos: si la salida todavía se conserva para recuperarla.

output_expires_attimestamp

Solo en ejecuciones con retención cero de datos: cuándo se elimina una salida conservada si nadie la ha leído.

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
}

Listar ejecuciones

GET/v1/runs

Devuelve las ejecuciones, de la más reciente a la más antigua.

Consulta

limitinteger

De 1 a 100. Activa las respuestas paginadas.

cursorstring

El next_cursor de la página anterior.

statusstring

Devuelve solo las ejecuciones con este estado.

schedulestring

Devuelve solo las ejecuciones iniciadas por esta programación.

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…"
}

Sin limit ni cursor, la respuesta es un array simple con las 100 ejecuciones coincidentes más recientes. Consulta paginación.

Obtener una ejecución

GET/v1/runs/{id}

Devuelve el objeto de ejecución. Consúltalo repetidamente hasta que el estado sea final, o usa eventos o un callback.

Transmitir eventos

GET/v1/runs/{id}/events

Un flujo de eventos enviados por el servidor (SSE). Reproduce todos los eventos registrados y después envía los nuevos a medida que ocurren. Cuando la ejecución es final, envía done con el objeto de ejecución y se cierra.

Cabeceras

Last-Event-IDinteger

Reanuda después de este ID de evento, por ejemplo al reconectar tras una conexión interrumpida.

Texto

: 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", …}

El data de cada mensaje es un objeto de evento con id, type, data y created_at, salvo done, que lleva el objeto de ejecución. Las líneas que empiezan por dos puntos son comentarios; se envía un comentario de latido cada 15 segundos. Los tipos de evento se listan en tipos de evento. Desconectarse no cancela la ejecución.

Terminal

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

Cancelar una ejecución

POST/v1/runs/{id}/cancel

Cancela una ejecución que está en reserving, queued, starting o running y devuelve el objeto de ejecución. Una ejecución que ya ha terminado se devuelve sin cambios.

Cancelar detiene el worker. No deshace nada de lo que el agente ya hizo a través de una conexión.

Leer la definición de una ejecución

GET/v1/runs/{id}/definition

Devuelve la definición que usó realmente la ejecución, preparada para revisarla antes de volver a ejecutarla.

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 es la definición resuelta. Los nombres de archivo se sustituyen por los IDs que se usaron, y se rellenan los campos guardados de un flujo de trabajo. El nombre del flujo de trabajo y el callback se omiten. Las conexiones guardadas conservan solo su referencia y sus listas de permitidos. Las conexiones en línea pierden sus credenciales y cualquier secreto de su URL.

requires_credentials lista las conexiones en línea que necesitan que se restauren las credenciales o su URL original. Para ejecutarla de nuevo, vuelve a añadirlas, elige un nuevo max_cost_micros y envía la solicitud a POST /v1/runs. Las referencias a conexiones guardadas se resuelven de nuevo en ese momento, y la solicitud falla si se ha eliminado un archivo o una conexión a los que hace referencia.

La definición conserva tu prompt, tu entrada y el contenido de los archivos en línea tal como se enviaron. No incluyas secretos en ellos.

Ejecuciones con retención cero de datos

Una ejecución con zero_data_retention devuelve su salida una vez. El primer GET /v1/runs/{id} tras terminar incluye output y la elimina; las lecturas posteriores la omiten e informan output_available: false. Si la ejecución tiene un callback, este entrega la salida y GET la deja en su sitio hasta entonces. Una salida no entregada se elimina como máximo después de una hora.

El flujo de eventos funciona mientras la ejecución trabaja y unos minutos después. GET /v1/runs/{id}/definition devuelve 410 y las listas de ejecuciones nunca incluyen la salida. En el servicio alojado, cost_micros incluye el recargo y el presupuesto debe cubrirlo.