Execuções · Documentação da Ephemeral

Inicie execuções, acompanhe-as e leia os resultados. Todos os endpoints desta página funcionam com chaves de membro e de administrador. Veja as execuções para o ciclo de vida e os limites.

Iniciar uma execução

POST/v1/runs

Cria uma execução e a coloca na fila. Envie um prompt ou o nome de um workflow salvo.

Corpo

promptstring

A tarefa. Obrigatório, a menos que workflow esteja definido; com um fluxo de trabalho, substitui o prompt salvo. Até 128 KiB.

inputany JSON

Dados para a tarefa, passados ao agente como JSON. Até 1 MiB.

workflowstring

Nome de um fluxo de trabalho salvo. Os outros campos de definição que você enviar substituem os salvos.

modelstring

ID do modelo. Assume por padrão default_model de GET /v1/models.

filesarray

Até 32 entradas, cada uma {"file": "<id or name>", "path": "..."} ou {"path": "...", "content": "..."}. Veja os arquivos.

connectionsobject

Até 16 conexões, identificadas pelo nome que o agente vê. Cada uma é {"ref": "<saved name>"} com allowed_methods ou allowed_tools opcionais, ou uma definição em linha. Veja as conexões.

descriptionstring

O que a execução faz, para pessoas e agentes. Até 500 caracteres. Inofensivo em uma execução inline; com um fluxo de trabalho, substitui a descrição salva.

input_schemaobject

Um JSON Schema com o qual input deve corresponder; se não corresponder, retorna 400 com o caminho e o motivo, por exemplo input.city: required. Com um fluxo de trabalho, substitui o schema salvo. Veja descrever a entrada e a saída.

output_schemaobject

Um JSON Schema com o qual a saída da execução deve corresponder; se não corresponder, a execução termina em failed. Com um fluxo de trabalho, substitui o schema salvo. Veja descrever a entrada e a saída.

timeout_secondsinteger

De 1 a 3600. Padrão: 300.

shellboolean

Permite que o agente execute comandos de shell e grave arquivos no seu diretório de trabalho. Padrão: true.

webboolean | object

Permite que o agente busque páginas, chame APIs públicas e pesquise por meio do Ephemeral. true, ou { "allow": [domains], "search": false } para limitá-lo. Padrão: desativado. Veja o acesso à web.

zero_data_retentionboolean

Não registra nada do conteúdo da execução: sem eventos guardados, sem definição, e a saída é devolvida uma única vez. Execuções hospedadas custam mais. Veja retenção zero de dados. O padrão é false.

max_cost_microsinteger

Orçamento, de 1 a 100.000.000. Assume por padrão default_max_cost_micros de GET /v1/me. No serviço hospedado, deve cobrir a cobrança de computação pelo timeout completo. Veja os orçamentos.

callbackobject

{"url": "...", "secret": "..."} para uma requisição assinada quando a execução termina. Veja os callbacks.

Cabeçalhos

Idempotency-Keystring

Opcional, até 200 caracteres. Uma chave repetida retorna a execução existente com 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
  }'

A resposta é 202 Accepted com o novo objeto de execução. Uma requisição que falha na validação retorna 400 e não cria nada. No serviço hospedado, 402 significa que seus créditos disponíveis não cobrem o orçamento.

O objeto de execução

idstring

ID da execução, como run_4abb0f420c6623a12d2889610eb67284.

statusstring

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

outputstring

A resposta final do agente. Omitida até existir uma. Até 1 MiB; uma resposta maior é cortada nesse ponto e um evento output_truncated informa isso.

errorstring

Por que a execução não foi concluída com sucesso. Omitido quando vazio.

created_attimestamp

Quando a execução foi criada.

started_attimestamp

Quando ela saiu da fila. Omitido antes disso.

finished_attimestamp

Quando ela chegou a um status final. Omitido antes disso.

max_cost_microsinteger

O orçamento da execução.

cost_microsinteger

Custo até o momento. Provisório até que billing_pending seja false em uma execução concluída. Omitido quando zero.

billing_pendingboolean

Se o custo ainda precisa ser liquidado.

schedule_idstring

O agendamento que iniciou a execução, quando houve um.

zero_data_retentionboolean

true em uma execução com retenção zero de dados.

surcharge_percentinteger

A taxa do acréscimo, em execuções com retenção zero de dados no serviço hospedado.

surcharge_microsinteger

A parte de cost_micros acrescentada pelo acréscimo de retenção zero de dados. Omitida quando é zero.

output_availableboolean

Somente em execuções com retenção zero de dados: se a saída ainda está guardada para ser recuperada.

output_expires_attimestamp

Somente em execuções com retenção zero de dados: quando uma saída guardada é apagada se ninguém a leu.

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 execuções

GET/v1/runs

Retorna as execuções, das mais recentes às mais antigas.

Consulta

limitinteger

De 1 a 100. Ativa as respostas paginadas.

cursorstring

O next_cursor da página anterior.

statusstring

Retorna apenas as execuções com este status.

schedulestring

Retorna apenas as execuções iniciadas por este agendamento.

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

Sem limit ou cursor, a resposta é um array simples com as 100 execuções correspondentes mais recentes. Veja a paginação.

Obter uma execução

GET/v1/runs/{id}

Retorna o objeto de execução. Consulte-o até que o status seja final ou use eventos ou um callback.

Transmitir eventos

GET/v1/runs/{id}/events

Um stream de eventos enviados pelo servidor. Ele reproduz todos os eventos registrados e depois envia os novos conforme acontecem. Quando a execução é final, envia done com o objeto de execução e fecha.

Cabeçalhos

Last-Event-IDinteger

Retoma depois deste ID de evento, por exemplo ao se reconectar depois de uma queda de conexão.

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

O data de cada mensagem é um objeto de evento com id, type, data e created_at, exceto done, que traz o objeto de execução. As linhas que começam com dois-pontos são comentários; um comentário de heartbeat é enviado a cada 15 segundos. Os tipos de evento estão listados em tipos de evento. Desconectar não cancela a execução.

Terminal

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

Cancelar uma execução

POST/v1/runs/{id}/cancel

Cancela uma execução em reserving, queued, starting ou running e retorna o objeto de execução. Uma execução que já terminou é retornada sem alterações.

Cancelar interrompe o worker. Não desfaz nada que o agente já tenha feito por meio de uma conexão.

Ler a definição de uma execução

GET/v1/runs/{id}/definition

Retorna a definição que a execução realmente usou, preparada para revisão antes de executá-la de novo.

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 é a definição resolvida. Os nomes de arquivo são substituídos pelos IDs que foram usados, e os campos salvos de um fluxo de trabalho são preenchidos. O nome do fluxo de trabalho e o callback são omitidos. As conexões salvas mantêm apenas a referência e as listas de permissões. As conexões em linha perdem as credenciais e quaisquer segredos presentes na URL.

requires_credentials lista as conexões em linha que precisam ter as credenciais ou a URL original restauradas. Para executar de novo, adicione-as de volta, escolha um novo max_cost_micros e envie a requisição para POST /v1/runs. As referências a conexões salvas são resolvidas de novo nesse momento, e a requisição falha se um arquivo ou uma conexão referenciada tiver sido excluído.

A definição guarda o seu prompt, a entrada e o conteúdo dos arquivos em linha como foram enviados. Não coloque segredos neles.

Execuções com retenção zero de dados

Uma execução com zero_data_retention devolve sua saída uma vez. O primeiro GET /v1/runs/{id} depois do fim inclui output e a apaga; as leituras seguintes a omitem e informam output_available: false. Se a execução tem um callback, ele entrega a saída e o GET a deixa onde está até lá. Uma saída não entregue é apagada em no máximo uma hora.

O fluxo de eventos funciona enquanto a execução trabalha e por alguns minutos depois. GET /v1/runs/{id}/definition retorna 410, e as listas de execuções nunca incluem a saída. No serviço hospedado, cost_micros inclui o acréscimo e o orçamento precisa cobri-lo.