---
title: schedules
description: Manage recurring measurement settings for a Workspace.
canonical_url: https://orchestor.io/docs/en/cli/schedules
markdown_url: https://orchestor.io/docs/en/cli/schedules.md
contentType: reference
---

# schedules

`orc schedules` manages recurring measurement settings saved for the selected Workspace. Configure the default language, execution location, target channels, and daily or weekly cadence; inspect upcoming windows, update settings, pause, resume, delete, or run a specified prompt once. The existing measurement engine processes prompts that are active measurement targets within the Workspace.

Authentication and Workspace selection are required. Select the target with `--workspace <workspace-id>` or `ORCHESTOR_WORKSPACE_ID`. Each Workspace can have one saved configuration, and the schedule ID equals the Workspace ID. Creating, updating, pausing, resuming, deleting, and running once require `workspace:settings`.

Cadence is `daily` or `weekly`, with execution windows based on UTC. A weekly contract makes the effective cadence weekly even when `daily` is requested. Settings do not accept arbitrary cron expressions, time zones, API paths, or past observation IDs or report IDs as execution targets.

## Usage

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

*List recurring measurement settings saved for the selected Workspace.*

## How it works

Settings are saved as server-side measurement configuration for the selected Workspace, not as a local file. Creation and updates save a configuration revision, and the existing recurring measurement engine processes active prompts and channels allowed by the contract. No separate scheduler or arbitrary API handler is needed for configuration.

Daily windows use UTC date boundaries; weekly windows use Monday in UTC. The next timestamp returned is the window start, not a completion time or guaranteed start time. If configured `daily` differs from contractual weekly limits, inspect `effective_cadence`.

Lists return only saved settings. An empty list does not mean all automated measurements have stopped. A Workspace without saved settings may still be eligible for recurring measurement under the existing default cadence. Pause and delete suppress future recurring measurements through saved settings.

## Subcommands

### `list`

Lists settings saved for the selected Workspace. Result `data` is an empty array or an array of one item. Returns ID, paused state, UTC basis, configuration, and the latest recurring measurement run. There is no implicit list operation without a subcommand or `ls` alias.

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

#### Examples

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

*Inspect settings as JSON.*

### `create`

Saves measurement defaults to create recurring measurement settings for the Workspace. `default_location`, `default_language`, and `platform_selection` are required; `cadence` can be `daily` or `weekly`. When omitted, effective cadence follows the existing contract and cadence settings. There is no interactive input guide; pass JSON with `--stdin`. Returns `409 ALREADY_EXISTS` if saved settings already exist. Recreate deleted settings by supplying the required fields.

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

#### Unique 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.

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

#### Examples

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

*Create daily recurring settings from a JSON file.*

### `get`

Provide a schedule ID equal to the Workspace ID to retrieve one saved configuration. `configuration.cadence` is the saved cadence; `configuration.effective_cadence` is the effective cadence limited by the contract. `configuration.next_measurement_at_by_prompt` gives the start of the next UTC measurement window for each target prompt. Actual processing may start later within that window. `last_execution` is the latest recurring measurement run for the Workspace, or `null` if there is no history.

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

#### Examples

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

*Inspect settings, the next window, and latest recurring run.*

### `update`

Partially updates saved measurement settings. Omitted defaults and cadence are retained. Changes pass existing configuration validation, channel entitlement checks, and configuration revision persistence. Updating paused settings does not resume them. This operation does not stop an already started run.

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

#### Unique 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.

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

#### Examples

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

*Set saved cadence to weekly while retaining other defaults.*

### `delete`

Deletes saved settings and suppresses future recurring measurements. A deleted state is retained for suppression; past runs are not deleted. After deletion, `get`, `resume`, and `run` return `404`. Use `create` to recreate settings. DELETE requires confirmation; pass `--yes` in non-interactive execution.

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

#### Examples

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

*Delete recurring settings after confirmation.*

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

*Confirm deletion non-interactively.*

### `pause`

Pauses saved settings and excludes the Workspace from future recurring measurements. It does not cancel started or queued runs. Paused settings remain retrievable, but the map of next measurement windows becomes empty. Repeating the operation on paused settings retains the paused state.

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

#### Examples

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

*Pause future recurring measurements.*

### `resume`

Resumes paused saved settings. The Workspace becomes eligible for subsequent normal measurement windows; elapsed windows during the pause are not executed in a batch. Resuming does not change contractual cadence limits or prompt activation.

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

#### Examples

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

*Resume paused recurring settings.*

### `run`

Runs an explicitly specified prompt and model channel once in a Workspace with saved settings. `--prompt-id` and `--model-channel-id` are required. This does not immediately execute recurring measurements for the whole Workspace. It passes the same target and entitlement checks as existing manual measurements and returns the queued run ID. It does not change recurring cadence, the next window, or paused state. An explicit one-time run is possible even with paused settings.

```bash title="terminal"
orc schedules run <id> [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 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.

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

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

Type: `string`. Optional.

```bash title="terminal"
orc schedules run <id> --include-transcript <value>
```

#### Examples

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

*Run one active prompt once through the ChatGPT channel.*

## Examples

### Measurement configuration JSON

Set `default_location` to `global`, or `country` with a country code. For `platform_selection`, `all` selects the available set and `explicit` selects supported measurement channel IDs. Empty selections and unsupported direct provider API channels are rejected.

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

*Measurement configuration JSON*

### Review a creation request before sending

`--dry-run` displays the planned request without calling the API. It does not verify Workspace access, contract checks, or successful server validation.

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

*Review a creation request before sending*

### Save settings as JSON

Use this to inspect or compare saved settings. JSON output is a CLI envelope containing `success`, `data`, and `metadata`.

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

*Save settings as JSON*

### Partially update cadence only

Retains the default language, execution location, target channels, and current paused state.

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

*Partially update cadence only*

### Identify the same one-time request

One-time runs use Idempotency-Key. Use the same key when resending the same request, and a new key for a different measurement. Reusing a key with a different request body causes a conflict. Inspect the accepted run ID with [`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
```

*Identify the same one-time request*

## Troubleshooting

### Missing authentication or Workspace

Configure authentication and supply `--workspace` or `ORCHESTOR_WORKSPACE_ID`. Use the same Workspace ID as the schedule ID. A schedule ID for another Workspace returns `404`. For `403 RBAC_DENIED`, use a user with `workspace:settings` on the target Workspace.

### Existing settings error during creation

`409 ALREADY_EXISTS` indicates saved settings already exist. Inspect them with `get` and use `update` to change them. Paused settings also count as existing settings.

### JSON is rejected

Check required `create` fields, `daily` / `weekly` cadence, execution location, language tag, and supported measurement channel IDs. `targetType`, `targetId`, `cron`, and `timezone` are not configuration body fields. Correct the JSON file, inspect the request with `--dry-run`, and resend.

### Daily becomes weekly, or a run cannot execute

Inspect `configuration.effective_cadence` and Workspace contract and entitlements. Settings cannot override contractual cadence restrictions. For `run`, supply an active prompt in the Workspace and an available model channel. Acceptance does not mean measurement completion; inspect state using the returned run ID.

### Cannot resume after deletion

`resume` on deleted settings returns `404`. Prepare the required measurement defaults and recreate with `create`. Non-interactive deletion requires `--yes`.

### Unknown one-time execution response

If communication failure prevents receiving a response, resend with the same Idempotency-Key and body. If you already received a run ID, inspect its state first. For `409` caused by reuse with another body, resend with a key for the new operation.

## Related

- [`orc runs`](https://orchestor.io/docs/cli/runs.md): Inspect accepted measurement run state and results.
- [`orc billing`](https://orchestor.io/docs/cli/billing.md): Inspect Workspace contracts and entitlements.
- [Global options](https://orchestor.io/docs/cli/global-flags.md): Workspace selection, JSON output, stdin, and request previews.

## Permissions

Listing and detail retrieval require access to the selected Workspace. Mutations and `run` require `workspace:settings` on that Workspace. `run` also checks that the prompt is an active measurement target in that Workspace and that the specified model channel is entitled.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc schedules`:

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

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

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