​

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.

List recurring measurement settings saved for the selected Workspace.

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.

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.

Inspect settings as JSON.

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.

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

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

Type: string. Optional.

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

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

Type: string. Optional.

Create daily recurring settings from a JSON file.

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.

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

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.

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.

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

Type: string. Optional.

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.

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

Type: string. Optional.

Set saved cadence to weekly while retaining other defaults.

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.

Delete recurring settings after confirmation.

Confirm deletion non-interactively.

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.

Pause future recurring measurements.

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.

Resume paused recurring settings.

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.

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.

(required) Saved prompt ID in this workspace. Active and disabled prompts support manual execution; draft and archived targets do not.

Type: string. Optional.

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

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.

Optional persona reference forwarded to execution. Omit or use null to supply no reference override.; (use "null" or "reset" to clear)

Type: string. Optional.

Optional free-form region context forwarded to execution. Omit or use null for no override.; (use "null" or "reset" to clear)

Type: string. Optional.

Optional catalog region context forwarded to execution. Omit or use null for no override.; (use "null" or "reset" to clear)

Type: string. Optional.

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.

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.

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.

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.

Optional free-form classification stored with this execution and available to answer-list filters.; (use "null" or "reset" to clear)

Type: string. Optional.

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.

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.

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.

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.

Run one active prompt once through the ChatGPT channel.

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.

Measurement configuration JSON

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

Review a creation request before sending

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

Save settings as JSON

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

Partially update cadence only

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.

Identify the same one-time request

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.

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.

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.

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.

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

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.

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.

The following global options can be used with orc schedules:

For details and examples, see global options.