runs
orc runs は、保存したプロンプトの実行を作成し、状態と結果を取得し、cancelするコマンドです。一件ずつのrunと、複数requestをまとめる非同期バッチを扱います。
対象Workspaceへのアクセスと計測チャネルの利用権限を確認してください。新規計測は chatgpt-ui、gemini-ui、perplexity-ui、copilot-ui、google-ai-overview、google-ai-mode のconsumer surfaceを指定します。過去のチャネル識別子は読めますが、新規実行に使えるとは限りません。
使い方
orc runs create --prompt-id <prompt-id> --model-channel-id chatgpt-ui保存したpromptを一回実行します。
実行のcontextと保存
persona・region・language・countryを実行contextとして指定できます。tag ID・prompt type・asset・metadataはcontextとして保存され、metadataはroutingや権限を変えません。--include-transcript は既定falseの保存requestで、公開Answerに messages は返りません。retrievableな会話の保証ではありません。
バッチ期限は作成から24時間または48時間です。statusのcompletedやexpired数を成功数と混同しないでください。
サブコマンド
list
Workspaceの実行を一覧表示します。--status は queued、running、succeeded、failed、canceled から指定し、省略すると全状態を含みます。
orc runs list [options]固有のオプション
--status
Return only executions in this state. Omit to include every state.; enum: queued|running|succeeded|failed|canceled
型: string。任意。
orc runs list --status <value>create
保存済みprompt IDと、計測に使えるconsumer AI surfaceの --model-channel-id が必要です。activeまたはdisabledのpromptを手動実行できますが、draft・archivedは対象外です。直接vendor APIチャネルやlegacy aliasは新規計測に使えません。topic・brand IDを指定する場合はpromptの所属と一致する必要があり、対象の移動や差し替えではありません。
orc runs create [options]固有のオプション
--idempotency-key
Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.
型: string。任意。
orc runs create --idempotency-key <value>--prompt-id
(required) Saved prompt ID in this workspace. Active and disabled prompts support manual execution; draft and archived targets do not.
型: string。任意。
orc runs create --prompt-id <value>--model-channel-id
(required) Consumer AI surface available for new measurements. Direct vendor API channels and legacy aliases are not accepted; historical channel identities remain readable.; enum: chatgpt-ui|gemini-ui|perplexity-ui|copilot-ui|google-ai-overview|google-ai-mode
型: string。任意。
orc runs create --model-channel-id <value>--persona
Optional free-form persona context forwarded to execution. Omit or use null to supply no free-form override.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --persona <value>--persona-id
Optional persona reference forwarded to execution. Omit or use null to supply no reference override.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --persona-id <value>--region
Optional free-form region context forwarded to execution. Omit or use null for no override.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --region <value>--region-id
Optional catalog region context forwarded to execution. Omit or use null for no override.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --region-id <value>--topic-id
Optional assertion of the tracked prompt topic. If supplied, it must match the prompt topic; it does not move the prompt. Omit or use null to use the prompt topic.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --topic-id <value>--brand-id
Optional assertion of the tracked prompt brand. If supplied, it must match the prompt brand; it does not select another analysis target.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --brand-id <value>--asset-id
Optional asset context stored with the execution request. This does not create or retrieve an asset.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --asset-id <value>--tag-ids
Optional tag IDs stored as context for this execution. An explicit empty array records no tags.; csv; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --tag-ids <value>--prompt-type
Optional free-form classification stored with this execution and available to answer-list filters.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --prompt-type <value>--language-code
Optional language override passed to the selected observation channel. Use a language code supported by that channel. Omit or use null for no explicit override.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --language-code <value>--country-code
Optional observation-country override, such as US or JP. Omit or use null for no explicit override.; (use "null" or "reset" to clear)
型: string。任意。
orc runs create --country-code <value>--metadata
Optional client correlation metadata stored with the execution request. It does not change routing or grant access.; (JSON object, e.g. '{"custom_id":"x"}'); (use "null" or "reset" to clear)
型: string。任意。
orc runs create --metadata <value>--include-transcript
Optional transcript-retention request forwarded to execution. Defaults to false. The public Answer response does not expose a messages field; this option does not guarantee a retrievable transcript.
型: string。任意。
orc runs create --include-transcript <value>get
run IDで状態を取得します。--wait は非同期完了を待ち、--timeout で待機時間、--poll-interval で照会間隔を指定します。既定の照会間隔は5秒です。
orc runs get <id> [options]cancel
run IDを指定してcancelを要求します。要求後の状態は get で確認してください。
orc runs cancel <id> [options]固有のオプション
--idempotency-key
Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.
型: string。任意。
orc runs cancel <id> --idempotency-key <value>results get
run IDを指定して実行結果を取得します。状態の確認は runs get、保存された回答の詳細は orc answers で行います。
orc runs results get <id> [options]batches list
バッチを一覧表示します。running、canceling、completed で絞り込めます。completed は失敗などの終端結果も含み、全件成功を示しません。
orc runs batches list [options]固有のオプション
--status
Batch processing state. Omit to include every state. completed includes unsuccessful terminal outcomes.; enum: running|canceling|completed
型: string。任意。
orc runs batches list --status <value>batches create
複数のプロンプト実行requestを非同期バッチとして作成します。引数、flag、本文、非同期動作は同じです。1〜10,000件の requests を指定し、各 custom_id はバッチ内で一意にします。
orc runs batches create [options]固有のオプション
--idempotency-key
Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.
型: string。任意。
orc runs batches create --idempotency-key <value>--requests
(required) One to 10,000 execution requests. Every custom_id must be unique within this batch. Use separate requests for different prompts or channels.; JSON array of objects (use --stdin for large resources)
型: string。任意。
orc runs batches create --requests <value>--metadata
Optional client metadata stored with the batch. Omit or use null for no supplied metadata.; (JSON object, e.g. '{"custom_id":"x"}'); (use "null" or "reset" to clear)
型: string。任意。
orc runs batches create --metadata <value>--completion-window
Requested execution window, starting at creation. Defaults to 24h; 48h allows a longer deadline. The expiry count reports requests marked expired, not successful completion.; enum: 24h|48h
型: string。任意。
orc runs batches create --completion-window <value>batches get
作成または一覧で返されたbatch IDで状態を取得します。--wait、--timeout、--poll-interval を使用できます。
orc runs batches get <id> [options]batches delete
batch IDを指定してバッチを削除します。削除を実行する前に対象IDを確認し、非対話の確認には --yes を指定します。
orc runs batches delete <id> [options]batches cancel
batch IDを指定してバッチのcancelを要求します。以後のstatusは get で確認します。
orc runs batches cancel <id> [options]固有のオプション
--idempotency-key
Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.
型: string。任意。
orc runs batches cancel <id> --idempotency-key <value>batches results get
完了したバッチの結果を取得します。custom_id で入力と結果を対応させ、成功・失敗を各結果で確認します。cursorによるページ送りでは同じbatch IDを維持します。
orc runs batches results get <id> [options]使用例
受理済みrunの完了を待ちます。
orc runs get <run-id> --wait --timeout 5m --json受理済みrunの完了を待ちます。
バッチの入力を用意します。
{
"requests": [
{
"custom_id": "measurement-1",
"params": {
"prompt_id": "<prompt-id>",
"model_channel_id": "chatgpt-ui"
}
}
],
"completion_window": "24h"
}バッチの入力を用意します。
バッチ結果を取得します。
orc runs batches results get <batch-id> --jsonバッチ結果を取得します。
再試行と結果の確認
再試行には同じmethod・path・query・正確な本文と --idempotency-key を使います。keyはtrim後1〜255文字で24時間保持します。本文のJSON空白変更も別の本文になり得ます。完了応答は再実行せず返し、異なるrequestとの再利用は 409 idempotency_error、処理中は 409 idempotency_in_progress と Retry-After: 2 を返します。
必要な権限
認証し、対象Workspaceを選択して実行します。対象Workspaceへのアクセスが必要です。
グローバルオプション
orc runs では、次のグローバルオプションを使用できます。
各オプションの詳細と使用例は、グローバルオプションを参照してください。