---
title: schedules
description: Workspaceの定期観測設定を管理する。
canonical_url: https://orchestor.io/docs/cli/schedules
markdown_url: https://orchestor.io/docs/cli/schedules.md
contentType: reference
---

# schedules

`orc schedules` は、選択中のWorkspaceに保存した定期観測設定を管理します。観測の既定言語・実行場所・対象チャネルと日次または週次の周期を設定し、予定の確認、設定変更、休止・再開・削除、指定したプロンプトの一回実行を行えます。既存の観測エンジンが、Workspace内の観測対象として有効なプロンプトを処理します。

実行には認証情報とWorkspaceの選択が必要です。`--workspace <workspace-id>` または `ORCHESTOR_WORKSPACE_ID` で対象を指定します。保存できる設定はWorkspaceごとに一件で、schedule IDはWorkspace IDと同じです。作成・変更・休止・再開・削除・一回実行には `workspace:settings` 権限が必要です。

周期は `daily` または `weekly`、実行窓の基準はUTCです。週次の契約では `daily` を指定しても有効な周期は週次になります。任意のcron式、タイムゾーン、APIパス、過去のobservation IDやreport IDを実行対象に指定する設定はありません。

## 使い方

```bash title="terminal"
orc schedules list --workspace <workspace-id>
```

*選択したWorkspaceに保存済みの定期観測設定を一覧にします。*

## 動作の流れ

設定はローカルファイルではなく、選択したWorkspaceのサーバー側の観測設定として保存します。作成や変更は設定revisionを保存し、既存の定期観測エンジンが有効なプロンプトと契約で許可されたチャネルを処理します。設定のために別のスケジューラーや任意のAPIハンドラーを作る必要はありません。

日次はUTCの日付境界、週次はUTCの月曜日を基準に観測窓を計算します。取得結果の次回時刻はその窓の開始で、完了時刻や開始の保証ではありません。設定上の `daily` と契約上の週次制限が異なる場合は、`effective_cadence` を確認してください。

一覧は保存済み設定だけを返します。空の一覧は自動観測全体が停止したことを意味しません。保存済み設定がないWorkspaceも、既存の既定周期による定期観測の対象となる場合があります。休止・削除は保存済み設定を通じて将来の定期観測を抑止する操作です。

## サブコマンド

### `list`

選択中のWorkspaceに保存済みの設定を一覧にします。結果の `data` は空配列または一件の配列です。ID、休止状態、UTCの基準、設定と直近の定期観測runを返します。サブコマンドを省略した一覧実行や `ls` aliasはありません。

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

#### 使用例

```bash title="terminal"
orc schedules list --workspace <workspace-id> --json
```

*設定をJSON形式で確認します。*

### `create`

観測の既定値を保存して、Workspaceの定期観測設定を作成します。`default_location`、`default_language`、`platform_selection` が必須で、`cadence` は `daily` または `weekly` を指定できます。省略時の有効な周期は既存の契約と周期設定に従います。対話式の入力案内はなく、JSONを `--stdin` で渡せます。保存済み設定が存在すると `409 ALREADY_EXISTS` を返します。削除した設定は、必須項目を指定して作り直せます。

```bash title="terminal"
orc schedules create [options]
```

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

##### `--default-location`

(required) Execution location. Choose global without code, or country with an uppercase two-letter code. Region and city locations are not accepted for execution.

型: `string`。任意。

```bash title="terminal"
orc schedules create --default-location <value>
```

##### `--default-language`

(required) Default execution language tag, such as ja-JP. Used when a measurement inherits the workspace language.

型: `string`。任意。

```bash title="terminal"
orc schedules create --default-language <value>
```

##### `--platform-selection`

(required) Choose all eligible observation channels, or provide a non-empty explicit set. Direct provider API channels are not supported for saved measurement configuration.

型: `string`。任意。

```bash title="terminal"
orc schedules create --platform-selection <value>
```

##### `--cadence`

Preferred cadence. A weekly billing entitlement cannot be accelerated to daily. Existing cadence is retained when omitted.; enum: daily|weekly

型: `string`。任意。

```bash title="terminal"
orc schedules create --cadence <value>
```

#### 使用例

```bash title="terminal"
orc schedules create --workspace <workspace-id> --stdin < schedule.json
```

*日次の定期観測設定をJSONファイルから作成します。*

### `get`

Workspace IDと同じschedule IDを指定して、一件の保存済み設定を取得します。`configuration.cadence` は保存した周期、`configuration.effective_cadence` は契約で制限した有効な周期です。`configuration.next_measurement_at_by_prompt` は対象プロンプトごとの次のUTC観測窓の開始時刻です。実際の処理開始は窓内で遅れる場合があります。`last_execution` はそのWorkspaceの直近の定期観測runで、履歴がなければ `null` です。

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

#### 使用例

```bash title="terminal"
orc schedules get <workspace-id> --workspace <workspace-id> --json
```

*設定、次の観測窓と直近の定期観測runを確認します。*

### `update`

保存済みの観測設定を部分更新します。省略した既定値と周期は保持します。変更内容は既存の設定検証、チャネルの利用権限確認と設定revisionの保存を通ります。休止中の設定を更新しても再開しません。開始済みのrunを中止する操作ではありません。

```bash title="terminal"
orc schedules update <id> [options]
```

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

##### `--default-location`

Execution location. Choose global without code, or country with an uppercase two-letter code. Region and city locations are not accepted for execution.

型: `string`。任意。

```bash title="terminal"
orc schedules update <id> --default-location <value>
```

##### `--default-language`

Default execution language tag, such as ja-JP. Used when a measurement inherits the workspace language.

型: `string`。任意。

```bash title="terminal"
orc schedules update <id> --default-language <value>
```

##### `--platform-selection`

Choose all eligible observation channels, or provide a non-empty explicit set. Direct provider API channels are not supported for saved measurement configuration.

型: `string`。任意。

```bash title="terminal"
orc schedules update <id> --platform-selection <value>
```

##### `--cadence`

Preferred cadence. A weekly billing entitlement cannot be accelerated to daily. Existing cadence is retained when omitted.; enum: daily|weekly

型: `string`。任意。

```bash title="terminal"
orc schedules update <id> --cadence <value>
```

#### 使用例

```bash title="terminal"
orc schedules update <workspace-id> --workspace <workspace-id> --cadence weekly
```

*ほかの既定値を保持して、保存した周期を週次にします。*

### `delete`

保存済み設定を削除し、将来の定期観測を抑止します。抑止のための削除状態は保持され、過去のrunは削除しません。削除後の `get`・`resume`・`run` は `404` になります。再開するには `create` で設定を作り直します。DELETEは確認が必要で、非対話実行では `--yes` を指定します。

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

#### 使用例

```bash title="terminal"
orc schedules delete <workspace-id> --workspace <workspace-id>
```

*確認を経て定期観測設定を削除します。*

```bash title="terminal"
orc schedules delete <workspace-id> --workspace <workspace-id> --yes
```

*非対話で削除を確定します。*

### `pause`

保存済み設定を休止し、そのWorkspaceを以後の定期観測対象から除外します。開始済み・予約済みのrunのキャンセルは行いません。休止中の設定も取得できますが、次の観測窓のマップは空になります。休止済みの設定への繰り返し操作も休止状態を保持します。

```bash title="terminal"
orc schedules pause <id> [options]
```

#### 使用例

```bash title="terminal"
orc schedules pause <workspace-id> --workspace <workspace-id>
```

*将来の定期観測を休止します。*

### `resume`

休止した保存済み設定を再開します。以後の通常の観測窓で対象となり、休止中に過ぎた窓をまとめて実行する処理はありません。再開しても契約の周期制限やプロンプトの有効状態は変わりません。

```bash title="terminal"
orc schedules resume <id> [options]
```

#### 使用例

```bash title="terminal"
orc schedules resume <workspace-id> --workspace <workspace-id>
```

*休止した定期観測設定を再開します。*

### `run`

保存済み設定のあるWorkspaceで、明示したプロンプトとモデルチャネルを一回実行します。`--prompt-id` と `--model-channel-id` が必要です。Workspace全体の定期観測を即時実行する操作ではなく、既存の手動観測と同じ対象・利用権限の確認を通り、キューに入れたrun IDを返します。定期観測の周期・次の窓や休止状態は変更しません。休止した設定でも明示的な一回実行は可能です。

```bash title="terminal"
orc schedules run <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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --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 schedules run <id> --include-transcript <value>
```

#### 使用例

```bash title="terminal"
orc schedules run <workspace-id> --workspace <workspace-id> --prompt-id <prompt-id> --model-channel-id chatgpt-ui --json
```

*一件の有効なプロンプトをChatGPTチャネルで一回実行します。*

## 使用例

### 観測設定のJSON

`default_location` は `global`、または国コード付きの `country` を指定します。`platform_selection` の `all` は利用可能な集合、`explicit` は対応する観測チャネルIDの選択です。空の選択や非対応の直接provider APIチャネルは受理されません。

```json title="schedule.json"
{
  "cadence": "daily",
  "default_location": {
    "level": "country",
    "code": "JP"
  },
  "default_language": "ja-JP",
  "platform_selection": {
    "mode": "explicit",
    "ids": [
      "chatgpt-ui"
    ]
  }
}
```

*観測設定のJSON*

### 作成requestを送信前に確認する

`--dry-run` は送信予定のrequestを表示し、APIを呼び出しません。Workspaceへのアクセス、契約やサーバー側の検証が成功することまでは確認しません。

```bash title="terminal"
orc schedules create --workspace <workspace-id> --stdin < schedule.json --dry-run
```

*作成requestを送信前に確認する*

### 設定をJSONで保存する

保存済み設定の確認や比較に使用します。JSON出力は `success`、`data`、`metadata` を持つCLI envelopeです。

```bash title="terminal"
orc schedules list --workspace <workspace-id> --json --output schedules.json
```

*設定をJSONで保存する*

### 周期だけを部分更新する

既定言語、実行場所、対象チャネルと現在の休止状態を保持します。

```bash title="terminal"
printf '%s\n' '{"cadence":"weekly"}' | orc schedules update <workspace-id> --workspace <workspace-id> --stdin
```

*周期だけを部分更新する*

### 同じ一回実行requestを識別する

一回実行にはIdempotency-Keyを使用します。同じrequestの再送では同じキーを使い、別の観測には新しいキーを指定してください。同じキーを異なるrequest本文へ再利用すると競合します。受理後のrun IDは [`orc runs get`](https://orchestor.io/docs/cli/runs.md) で確認できます。

```bash title="terminal"
orc schedules run <workspace-id> --workspace <workspace-id> --prompt-id <prompt-id> --model-channel-id chatgpt-ui --idempotency-key <request-key> --json
```

*同じ一回実行requestを識別する*

## トラブルシューティング

### 認証またはWorkspaceが不足している

認証情報を設定し、`--workspace` または `ORCHESTOR_WORKSPACE_ID` を指定してください。schedule IDにも同じWorkspace IDを使います。別のWorkspaceのschedule IDでは `404` を返します。`403 RBAC_DENIED` の場合は、対象Workspaceの `workspace:settings` 権限を持つ利用者で操作してください。

### 作成時に既存設定のエラーになる

`409 ALREADY_EXISTS` は、保存済み設定がすでにあることを示します。`get` で内容を確認し、`update` を使って変更してください。休止中の設定も存在する設定として扱います。

### JSONが受理されない

`create` の必須項目、`daily` / `weekly` の周期、実行場所と言語タグ、対応する観測チャネルIDを確認してください。`targetType`、`targetId`、`cron`、`timezone` は設定本文の項目ではありません。JSONファイルを修正して `--dry-run` でrequestを確認してから再送してください。

### 日次を指定しても週次になる、またはrunを実行できない

`configuration.effective_cadence` とWorkspaceの契約・利用権限を確認してください。設定で契約の周期制限を上書きすることはできません。`run` にはそのWorkspaceの有効なプロンプトと利用可能なモデルチャネルを指定します。runの受理は観測の完了を意味しないため、返ったrun IDで状態を確認してください。

### 削除後に再開できない

削除した設定への `resume` は `404` です。必須の観測既定値を用意して `create` で作り直してください。非対話で削除する場合は `--yes` が必要です。

### 一回実行の応答が不明なまま終わった

通信障害などで応答を受け取れなかった場合は、同じIdempotency-Keyと同じ本文で再送してください。すでにrun IDを受け取っている場合は先にそのrunの状態を確認します。異なる本文へのキー再利用による `409` は、新しい操作用のキーで送信し直してください。

## 関連項目

- [`orc runs`](https://orchestor.io/docs/cli/runs.md): 受理した観測runの状態と結果を確認します。
- [`orc billing`](https://orchestor.io/docs/cli/billing.md): Workspaceの契約と利用権限を確認します。
- [グローバルオプション](https://orchestor.io/docs/cli/global-flags.md): Workspace指定、JSON出力、標準入力とrequestの事前確認を確認します。

## 必要な権限

一覧と詳細には、選択したWorkspaceへのアクセス権が必要です。設定を書き換える操作と `run` には、同じWorkspaceの `workspace:settings` 権限が必要です。`run` ではさらに、プロンプトがそのWorkspaceの有効な観測対象であることと、指定したモデルチャネルの利用権限を確認します。

## グローバルオプション

`orc schedules` では、次の[グローバルオプション](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)
- [`--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)

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

---

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