실행 · Ephemeral 문서

실행을 시작하고, 진행 상황을 따라가고, 결과를 읽습니다. 이 페이지의 모든 엔드포인트는 member 키와 admin 키로 사용할 수 있습니다. 수명 주기와 한도는 실행을 참고하세요.

실행 시작

POST/v1/runs

실행을 만들어 대기열에 넣습니다. prompt나 저장된 workflow의 이름 중 하나를 보냅니다.

본문

promptstring

작업 내용. workflow를 지정하지 않으면 필수입니다. 워크플로와 함께 보내면 저장된 프롬프트를 대체합니다. 최대 128 KiB.

inputany JSON

작업에 쓸 데이터. 에이전트에게 JSON으로 전달됩니다. 최대 1 MiB.

workflowstring

저장된 워크플로의 이름. 함께 보내는 다른 정의 필드는 저장된 값을 덮어씁니다.

modelstring

모델 ID. 기본값은 GET /v1/models의 default_model입니다.

filesarray

최대 32개 항목이며, 각 항목은 {"file": "<id or name>", "path": "..."} 또는 {"path": "...", "content": "..."}입니다. 파일을 참고하세요.

connectionsobject

에이전트에게 보이는 이름을 키로 하는 연결, 최대 16개. 각 연결은 allowed_methods나 allowed_tools를 선택적으로 덧붙인 {"ref": "<saved name>"} 또는 인라인 정의입니다. 연결을 참고하세요.

descriptionstring

실행이 하는 일을 사람과 에이전트를 위해 설명합니다. 최대 500자. 인라인 실행에서는 영향이 없고, 워크플로와 함께 쓰면 저장된 설명을 대체합니다.

input_schemaobject

input이 따라야 하는 JSON Schema. 일치하지 않으면 경로와 이유(예: input.city: required)와 함께 400이 반환됩니다. 워크플로와 함께 쓰면 저장된 스키마를 대체합니다. 입력과 출력 설명하기를 참고하세요.

output_schemaobject

실행의 출력이 따라야 하는 JSON Schema. 일치하지 않으면 실행은 failed로 끝납니다. 워크플로와 함께 쓰면 저장된 스키마를 대체합니다. 입력과 출력 설명하기를 참고하세요.

timeout_secondsinteger

1~3600. 기본값 300.

shellboolean

에이전트가 셸 명령을 실행하고 작업 디렉터리에 파일을 쓸 수 있게 합니다. 기본값 true.

webboolean | object

에이전트가 Ephemeral을 통해 페이지를 가져오고, 공개 API를 호출하고, 검색할 수 있게 합니다. true이거나, 제한하려면 { "allow": [domains], "search": false }입니다. 기본값은 꺼짐입니다. 웹 액세스를 참고하세요.

zero_data_retentionboolean

실행 내용을 전혀 기록하지 않습니다. 이벤트도 정의도 저장되지 않고, 출력은 한 번만 반환됩니다. 호스팅 실행은 비용이 더 듭니다. 데이터 무보존을 참조하세요. 기본값은 false입니다.

max_cost_microsinteger

예산, 1~100,000,000. 기본값은 GET /v1/me의 default_max_cost_micros입니다. 호스팅 서비스에서는 전체 타임아웃에 해당하는 컴퓨팅 요금을 감당할 수 있어야 합니다. 예산을 참고하세요.

callbackobject

실행이 끝났을 때 서명된 요청을 받을 {"url": "...", "secret": "..."}. 콜백을 참고하세요.

헤더

Idempotency-Keystring

선택 사항, 최대 200자. 같은 키를 다시 보내면 기존 실행을 200으로 반환합니다.

터미널

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
  }'

응답은 새 실행 객체가 담긴 202 Accepted입니다. 검증에 실패한 요청은 400을 반환하고 아무것도 만들지 않습니다. 호스팅 서비스에서 402는 사용 가능한 크레딧이 예산에 못 미친다는 뜻입니다.

실행 객체

idstring

run_4abb0f420c6623a12d2889610eb67284 같은 실행 ID.

statusstring

reserving, queued, starting, running, succeeded, failed, cancelled, timed_out, interrupted 중 하나.

outputstring

에이전트의 최종 답변. 답변이 나오기 전에는 생략됩니다. 최대 1 MiB이며, 더 긴 답변은 그 지점에서 잘리고 output_truncated 이벤트로 알려 줍니다.

errorstring

실행이 성공하지 못한 이유. 비어 있으면 생략됩니다.

created_attimestamp

실행이 만들어진 시각.

started_attimestamp

대기열을 떠난 시각. 그 전에는 생략됩니다.

finished_attimestamp

최종 상태에 도달한 시각. 그 전에는 생략됩니다.

max_cost_microsinteger

실행의 예산.

cost_microsinteger

현재까지의 비용. 끝난 실행에서 billing_pending이 false가 될 때까지는 잠정 값입니다. 0이면 생략됩니다.

billing_pendingboolean

비용이 아직 정산되어야 하는지 여부.

schedule_idstring

실행을 시작한 스케줄이 있으면 그 ID.

zero_data_retentionboolean

데이터 무보존 실행이면 true.

surcharge_percentinteger

호스팅 서비스의 데이터 무보존 실행에 적용되는 추가 요금 비율.

surcharge_microsinteger

cost_micros 중 데이터 무보존 추가 요금으로 더해진 부분. 0이면 생략됩니다.

output_availableboolean

데이터 무보존 실행에만 있음: 출력이 가져갈 수 있도록 아직 보관 중인지 여부.

output_expires_attimestamp

데이터 무보존 실행에만 있음: 아무도 읽지 않았을 때 보관 중인 출력이 삭제되는 시각.

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
}

실행 목록

GET/v1/runs

최신순으로 실행을 반환합니다.

쿼리

limitinteger

1~100. 페이지 단위 응답을 켭니다.

cursorstring

이전 페이지의 next_cursor.

statusstring

이 상태의 실행만 반환합니다.

schedulestring

이 스케줄이 시작한 실행만 반환합니다.

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

limit이나 cursor가 없으면 조건에 맞는 가장 최근 실행 100개의 일반 배열이 반환됩니다. 페이지네이션을 참고하세요.

실행 조회

GET/v1/runs/{id}

실행 객체를 반환합니다. 상태가 최종 상태가 될 때까지 이 엔드포인트를 폴링하거나, 이벤트나 콜백을 사용하세요.

이벤트 스트리밍

GET/v1/runs/{id}/events

서버 전송 이벤트(SSE) 스트림입니다. 기록된 모든 이벤트를 재생한 뒤 새 이벤트를 발생하는 대로 보냅니다. 실행이 최종 상태가 되면 실행 객체와 함께 done을 보내고 연결을 닫습니다.

헤더

Last-Event-IDinteger

이 이벤트 ID 이후부터 이어서 받습니다. 예를 들어 연결이 끊겼다가 다시 연결할 때 사용합니다.

텍스트

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

각 메시지의 data는 id, type, data, created_at을 가진 이벤트 객체입니다. 단, done은 실행 객체를 담습니다. 콜론으로 시작하는 줄은 주석이며, 하트비트 주석이 15초마다 전송됩니다. 이벤트 유형은 이벤트 유형에 정리되어 있습니다. 연결을 끊어도 실행은 취소되지 않습니다.

터미널

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

실행 취소

POST/v1/runs/{id}/cancel

reserving, queued, starting, running 상태의 실행을 취소하고 실행 객체를 반환합니다. 이미 끝난 실행은 변경 없이 그대로 반환됩니다.

취소하면 워커가 중지됩니다. 에이전트가 이미 연결을 통해 수행한 작업은 되돌려지지 않습니다.

실행 정의 조회

GET/v1/runs/{id}/definition

실행이 실제로 사용한 정의를 반환하며, 다시 실행하기 전에 검토할 수 있도록 정리되어 있습니다.

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는 확정된 정의입니다. 파일 이름은 실제로 사용된 ID로 바뀌고, 워크플로에 저장된 필드가 채워집니다. 워크플로 이름과 콜백은 포함되지 않습니다. 저장된 연결은 참조와 허용 목록만 남습니다. 인라인 연결은 자격 증명과 URL 안의 비밀 값이 제거됩니다.

requires_credentials는 자격 증명이나 원래 URL을 복원해야 하는 인라인 연결을 나열합니다. 다시 실행하려면 이를 채워 넣고, 새 max_cost_micros를 정한 뒤 요청을 POST /v1/runs로 보내세요. 저장된 연결 참조는 그 시점에 다시 해석되며, 참조한 파일이나 연결이 삭제되었다면 요청이 실패합니다.

정의에는 보낸 그대로의 프롬프트, 입력, 인라인 파일 내용이 남습니다. 여기에 비밀 값을 넣지 마세요.

zero_data_retention 실행은 출력을 한 번만 반환합니다. 실행이 끝난 뒤 첫 번째 GET /v1/runs/{id}는 output을 포함해 반환하고 삭제하며, 이후 읽기에서는 출력이 빠지고 output_available: false가 보고됩니다. 실행에 콜백이 있으면 콜백이 출력을 전달하고, 그때까지는 GET을 해도 출력이 남아 있습니다. 전달되지 않은 출력은 늦어도 1시간 뒤에 삭제됩니다.

이벤트 스트림은 실행 중과 종료 후 몇 분 동안 동작합니다. GET /v1/runs/{id}/definition은 410을 반환하고, 실행 목록에는 출력이 포함되지 않습니다. 호스팅 서비스에서는 cost_micros에 추가 요금이 포함되며 예산이 이를 감당해야 합니다.