ドキュメント
API リファレンスダッシュボードログイン今すぐ始める
ドキュメント
ダッシュボードログイン今すぐ始める

API リファレンス

実行

実行の開始、一覧、確認、ストリーミング、キャンセル。

実行を開始し、進行を追跡して、結果を読み取ります。このページのエンドポイントは、すべてメンバーキーと管理者キーで使えます。ライフサイクルと上限については、実行をご覧ください。

実行を開始

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 件の接続。キーはエージェントに見える名前です。各接続は、{"ref": "<saved name>"} に allowed_methods または allowed_tools を任意で加えたものか、インラインの定義です。接続をご覧ください。
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 } を指定します。デフォルトはオフです。Web アクセスをご覧ください。
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
実行 ID。run_4abb0f420c6623a12d2889610eb67284 など。
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
実行を開始したスケジュール (ある場合)。
zero_data_retentionboolean
ゼロデータ保持の実行では true。
surcharge_percentinteger
ホスト型サービスでのゼロデータ保持の実行に適用される追加料金の率。
surcharge_microsinteger
cost_micros のうち、ゼロデータ保持の追加料金による部分。ゼロの場合は省略されます。
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
Server-Sent Events のストリームです。記録済みのイベントをすべて再生した後、新しいイベントが発生するたびに送信します。実行が最終状態になると、実行オブジェクトを含む 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 に追加料金が含まれ、予算はそれを賄える額である必要があります。

© 2026 Ephemeral制作: erni.works
esc

「」に一致する項目はありません。