---
title: runs
description: プロンプト実行と非同期バッチを管理する。
canonical_url: https://orchestor.io/docs/cli/runs
markdown_url: https://orchestor.io/docs/cli/runs.md
contentType: reference
---

# runs

`orc runs` は、保存したプロンプトの実行を作成し、状態と結果を取得し、cancelするコマンドです。一件ずつのrunと、複数requestをまとめる非同期バッチを扱います。

対象Workspaceへのアクセスと計測チャネルの利用権限を確認してください。新規計測は `chatgpt-ui`、`gemini-ui`、`perplexity-ui`、`copilot-ui`、`google-ai-overview`、`google-ai-mode` のconsumer surfaceを指定します。過去のチャネル識別子は読めますが、新規実行に使えるとは限りません。

## 使い方

```bash title="terminal"
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` から指定し、省略すると全状態を含みます。

```bash title="terminal"
orc runs list [options]
```

#### 固有のオプション

##### `--status`

Return only executions in this state. Omit to include every state.; enum: queued|running|succeeded|failed|canceled

型: `string`。任意。

```bash title="terminal"
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の所属と一致する必要があり、対象の移動や差し替えではありません。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
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`。任意。

```bash title="terminal"
orc runs create --include-transcript <value>
```

### `get`

run IDで状態を取得します。`--wait` は非同期完了を待ち、`--timeout` で待機時間、`--poll-interval` で照会間隔を指定します。既定の照会間隔は5秒です。

```bash title="terminal"
orc runs get <id> [options]
```

### `cancel`

run IDを指定してcancelを要求します。要求後の状態は `get` で確認してください。

```bash title="terminal"
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`。任意。

```bash title="terminal"
orc runs cancel <id> --idempotency-key <value>
```

### `results get`

run IDを指定して実行結果を取得します。状態の確認は `runs get`、保存された回答の詳細は [`orc answers`](https://orchestor.io/docs/cli/answer.md) で行います。

```bash title="terminal"
orc runs results get <id> [options]
```

### `batches list`

バッチを一覧表示します。`running`、`canceling`、`completed` で絞り込めます。`completed` は失敗などの終端結果も含み、全件成功を示しません。

```bash title="terminal"
orc runs batches list [options]
```

#### 固有のオプション

##### `--status`

Batch processing state. Omit to include every state. completed includes unsuccessful terminal outcomes.; enum: running|canceling|completed

型: `string`。任意。

```bash title="terminal"
orc runs batches list --status <value>
```

### `batches create`

複数のプロンプト実行requestを非同期バッチとして作成します。引数、flag、本文、非同期動作は同じです。1〜10,000件の `requests` を指定し、各 `custom_id` はバッチ内で一意にします。

```bash title="terminal"
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`。任意。

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

型: `string`。任意。

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

型: `string`。任意。

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

型: `string`。任意。

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

### `batches get`

作成または一覧で返されたbatch IDで状態を取得します。`--wait`、`--timeout`、`--poll-interval` を使用できます。

```bash title="terminal"
orc runs batches get <id> [options]
```

### `batches delete`

batch IDを指定してバッチを削除します。削除を実行する前に対象IDを確認し、非対話の確認には `--yes` を指定します。

```bash title="terminal"
orc runs batches delete <id> [options]
```

### `batches cancel`

batch IDを指定してバッチのcancelを要求します。以後のstatusは `get` で確認します。

```bash title="terminal"
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`。任意。

```bash title="terminal"
orc runs batches cancel <id> --idempotency-key <value>
```

### `batches results get`

完了したバッチの結果を取得します。`custom_id` で入力と結果を対応させ、成功・失敗を各結果で確認します。cursorによるページ送りでは同じbatch IDを維持します。

```bash title="terminal"
orc runs batches results get <id> [options]
```

## 使用例

### 受理済みrunの完了を待ちます。

```bash title="terminal"
orc runs get <run-id> --wait --timeout 5m --json
```

*受理済みrunの完了を待ちます。*

### バッチの入力を用意します。

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

*バッチの入力を用意します。*

### バッチ結果を取得します。

```bash title="terminal"
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` では、次の[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を使用できます。

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%98%E3%83%AB%E3%83%97)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-%E5%87%BA%E5%8A%9B)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#%E5%87%BA%E5%8A%9B%E5%BD%A2%E5%BC%8F)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A3%E3%83%BC%E3%83%AB%E3%83%89%E3%81%AE%E6%8A%BD%E5%87%BA)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#%E5%80%A4%E3%81%A0%E3%81%91%E3%82%92%E5%87%BA%E5%8A%9B)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%B8%E3%81%AE%E5%87%BA%E5%8A%9B)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%9A%E3%83%BC%E3%82%B8%E9%80%81%E3%82%8A)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E4%BA%8B%E5%89%8D%E7%A2%BA%E8%AA%8D)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E7%9C%81%E7%95%A5)
- [`--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#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#%E6%A8%99%E6%BA%96%E5%85%A5%E5%8A%9B)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#%E3%81%99%E3%81%B9%E3%81%A6%E3%81%AE%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E5%8F%96%E5%BE%97)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E6%99%82%E9%96%93)
- [`--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#%E8%AA%AD%E3%81%BF%E5%8F%96%E3%82%8A%E5%B0%82%E7%94%A8%E3%83%A2%E3%83%BC%E3%83%89)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#%E5%A4%96%E9%83%A8%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%81%AE%E7%9B%AE%E5%8D%B0%E4%BB%98%E3%81%91)

各オプションの詳細と使用例は、[グローバルオプション](https://orchestor.io/docs/cli/global-flags.md)を参照してください。

---

[Documentation index](https://orchestor.io/docs/llms.txt)