runs batches
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.
Use separate requests for different prompts or channels. Acceptance does not mean measurement completion. Use the returned batch ID to inspect status and results with orc runs.
Usage
orc run --stdin < batch.jsonSubmit JSON requests as a batch.
Subcommands
create
The execution deadline defaults to 24 hours from creation; --completion-window 48h selects a longer deadline. The expiry count describes requests marked expired, not successful executions.
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>Examples
Prepare batch input.
{
"requests": [
{
"custom_id": "measurement-1",
"params": {
"prompt_id": "<prompt-id>",
"model_channel_id": "chatgpt-ui"
}
}
],
"completion_window": "24h"
}Prepare batch input.
Wait for completion.
orc run --stdin < batch.json --wait --timeout 5mWait for completion.
Retrying
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 batches:
For details and examples, see global options.