--- title: runs description: Manage prompt executions and asynchronous batches. canonical_url: https://orchestor.io/docs/en/cli/runs markdown_url: https://orchestor.io/docs/en/cli/runs.md contentType: reference --- # 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 ```bash title="terminal" orc runs create --prompt-id --model-channel-id chatgpt-ui ``` *Execute 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. ```bash title="terminal" 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. ```bash title="terminal" orc runs list --status ``` ### `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. ```bash title="terminal" 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. ```bash title="terminal" orc runs create --idempotency-key ``` ##### `--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. ```bash title="terminal" orc runs create --prompt-id ``` ##### `--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. ```bash title="terminal" orc runs create --model-channel-id ``` ##### `--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. ```bash title="terminal" orc runs create --persona ``` ##### `--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. ```bash title="terminal" orc runs create --persona-id ``` ##### `--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. ```bash title="terminal" orc runs create --region ``` ##### `--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. ```bash title="terminal" orc runs create --region-id ``` ##### `--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. ```bash title="terminal" orc runs create --topic-id ``` ##### `--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. ```bash title="terminal" orc runs create --brand-id ``` ##### `--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. ```bash title="terminal" orc runs create --asset-id ``` ##### `--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. ```bash title="terminal" orc runs create --tag-ids ``` ##### `--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. ```bash title="terminal" orc runs create --prompt-type ``` ##### `--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. ```bash title="terminal" orc runs create --language-code ``` ##### `--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. ```bash title="terminal" orc runs create --country-code ``` ##### `--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. ```bash title="terminal" orc runs create --metadata ``` ##### `--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. ```bash title="terminal" orc runs create --include-transcript ``` ### `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. ```bash title="terminal" orc runs get [options] ``` ### `cancel` Request cancellation by run ID. Inspect the resulting state with `get`. ```bash title="terminal" orc runs cancel [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. ```bash title="terminal" orc runs cancel --idempotency-key ``` ### `results get` Retrieve execution results by run ID. Inspect state with `runs get` and persisted answer details with [`orc answers`](https://orchestor.io/docs/en/cli/answer.md). ```bash title="terminal" orc runs results get [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. ```bash title="terminal" 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. ```bash title="terminal" orc runs batches list --status ``` ### `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. ```bash title="terminal" 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. ```bash title="terminal" orc runs batches create --idempotency-key ``` ##### `--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. ```bash title="terminal" orc runs batches create --requests ``` ##### `--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. ```bash title="terminal" orc runs batches create --metadata ``` ##### `--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. ```bash title="terminal" orc runs batches create --completion-window ``` ### `batches get` Retrieve state using a batch ID returned by creation or listing. Supports `--wait`, `--timeout`, and `--poll-interval`. ```bash title="terminal" orc runs batches get [options] ``` ### `batches delete` Delete a batch by ID. Verify the target ID before deleting and use `--yes` for non-interactive confirmation. ```bash title="terminal" orc runs batches delete [options] ``` ### `batches cancel` Request batch cancellation by ID. Inspect subsequent status with `get`. ```bash title="terminal" orc runs batches cancel [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. ```bash title="terminal" orc runs batches cancel --idempotency-key ``` ### `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. ```bash title="terminal" orc runs batches results get [options] ``` ## Examples ### Wait for an accepted run. ```bash title="terminal" orc runs get --wait --timeout 5m --json ``` *Wait for an accepted run.* ### Prepare batch input. ```json title="batch.json" { "requests": [ { "custom_id": "measurement-1", "params": { "prompt_id": "", "model_channel_id": "chatgpt-ui" } } ], "completion_window": "24h" } ``` *Prepare batch input.* ### Retrieve batch results. ```bash title="terminal" orc runs batches results get --json ``` *Retrieve 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](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc runs`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--wait`](https://orchestor.io/docs/cli/global-flags.md) - [`--timeout`](https://orchestor.io/docs/cli/global-flags.md) - [`--poll-interval`](https://orchestor.io/docs/cli/global-flags.md) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)