---
title: runs batches
description: Create a prompt execution batch.
canonical_url: https://orchestor.io/docs/en/cli/run
markdown_url: https://orchestor.io/docs/en/cli/run.md
contentType: reference
---

# 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`](https://orchestor.io/docs/en/cli/runs.md).

## Usage

```bash title="terminal"
orc run --stdin < batch.json
```

*Submit 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.

```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 <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.

```bash title="terminal"
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.

```bash title="terminal"
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.

```bash title="terminal"
orc runs batches create --completion-window <value>
```

## Examples

### Prepare batch input.

```json title="batch.json"
{
  "requests": [
    {
      "custom_id": "measurement-1",
      "params": {
        "prompt_id": "<prompt-id>",
        "model_channel_id": "chatgpt-ui"
      }
    }
  ],
  "completion_window": "24h"
}
```

*Prepare batch input.*

### Wait for completion.

```bash title="terminal"
orc run --stdin < batch.json --wait --timeout 5m
```

*Wait 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](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc runs batches`:

- [`--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)
- [`--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)