runs
orc runs creates saved prompt executions, retrieves state and results, and requests cancellation. It handles individual runs and asynchronous batches of multiple requests.
Verify target Workspace access and measurement channel entitlements. New measurements use consumer surfaces chatgpt-ui, gemini-ui, perplexity-ui, copilot-ui, google-ai-overview, or google-ai-mode. Historical channel identities remain readable but are not necessarily available for new execution.
Usage
orc runs create --prompt-id <prompt-id> --model-channel-id chatgpt-uiExecute a saved prompt once.
Execution context and retention
Supply persona, region, language, and country as execution context. Tag IDs, prompt type, asset, and metadata are stored as context; metadata does not change routing or access. --include-transcript is a retention request defaulting to false; the public Answer does not return messages. It does not guarantee a retrievable conversation.
Batch deadlines are 24 or 48 hours from creation. Do not treat completed status or expiry counts as success counts.
Subcommands
list
List Workspace executions. Filter with --status using queued, running, succeeded, failed, or canceled; omission includes every state.
orc runs list [options]Unique options
--status
Return only executions in this state. Omit to include every state.; enum: queued|running|succeeded|failed|canceled
Type: string. Optional.
orc runs list --status <value>create
Requires a saved prompt ID and a consumer AI surface --model-channel-id available for measurements. Active and disabled prompts allow manual execution; draft and archived prompts do not. Direct vendor API channels and legacy aliases are not accepted for new measurements. If supplied, topic and brand IDs must match the prompt; they do not move or replace its target.
orc runs create [options]Unique 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.
Type: string. Optional.
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.
Type: string. Optional.
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
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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.
Type: string. Optional.
orc runs create --include-transcript <value>get
Retrieve state by run ID. --wait waits for asynchronous completion, --timeout limits waiting, and --poll-interval sets the status request interval, defaulting to 5 seconds.
orc runs get <id> [options]cancel
Request cancellation by run ID. Inspect the resulting state with get.
orc runs cancel <id> [options]Unique 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.
Type: string. Optional.
orc runs cancel <id> --idempotency-key <value>results get
Retrieve execution results by run ID. Inspect state with runs get and persisted answer details with orc answers.
orc runs results get <id> [options]batches list
List batches, optionally filtering by running, canceling, or completed. completed also includes unsuccessful terminal outcomes; it does not mean every request succeeded.
orc runs batches list [options]Unique options
--status
Batch processing state. Omit to include every state. completed includes unsuccessful terminal outcomes.; enum: running|canceling|completed
Type: string. Optional.
orc runs batches list --status <value>batches create
orc run is the short entry point for orc runs batches create, creating multiple prompt execution requests as an asynchronous batch. Arguments, flags, body, and asynchronous behavior are identical. Supply 1–10,000 requests, with each custom_id unique within the batch.
orc runs batches create [options]Unique 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.
Type: string. Optional.
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)
Type: string. Optional.
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)
Type: string. Optional.
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
Type: string. Optional.
orc runs batches create --completion-window <value>batches get
Retrieve state using a batch ID returned by creation or listing. Supports --wait, --timeout, and --poll-interval.
orc runs batches get <id> [options]batches delete
Delete a batch by ID. Verify the target ID before deleting and use --yes for non-interactive confirmation.
orc runs batches delete <id> [options]batches cancel
Request batch cancellation by ID. Inspect subsequent status with get.
orc runs batches cancel <id> [options]Unique 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.
Type: string. Optional.
orc runs batches cancel <id> --idempotency-key <value>batches results get
Retrieve results of a completed batch. Correlate inputs and results by custom_id and inspect success or failure per result. Keep the same batch ID when paging with cursors.
orc runs batches results get <id> [options]Examples
Wait for an accepted run.
orc runs get <run-id> --wait --timeout 5m --jsonWait for an accepted run.
Prepare batch input.
{
"requests": [
{
"custom_id": "measurement-1",
"params": {
"prompt_id": "<prompt-id>",
"model_channel_id": "chatgpt-ui"
}
}
],
"completion_window": "24h"
}Prepare batch input.
Retrieve batch results.
orc runs batches results get <batch-id> --jsonRetrieve batch results.
Retrying and inspecting results
Retry with the same method, path, query, exact body, and --idempotency-key. Keys contain 1–255 characters after trimming and are retained for 24 hours. Changes to JSON whitespace can count as a different body. Completed responses replay without re-execution; reuse for another request returns 409 idempotency_error, and an in-progress request returns 409 idempotency_in_progress with Retry-After: 2.
Permissions
Authenticate and select the target Workspace. Access to that Workspace is required.
Global Options
The following global options can be used with orc runs:
For details and examples, see global options.