Getting started

​
Run the first observation and read its results

Sign in and select a workspace first. For another target, create a workspace. Replace WORKSPACE_ID and the website URL below with your target. These JSON examples use jq.

Beta users can use their saved CLI browser login. API keys require read_write permission and a measurement allowance for the target workspace.

​
1. Generate candidates from a website

orc observations create --workspace WORKSPACE_ID \
  --website https://example.com --region JP --language ja \
  --wait --timeout 10m --json
orc observations configurations get --workspace WORKSPACE_ID --json > configuration.json

After generation succeeds, review the brand, competitors, topics, prompts, region, language, and models. These are setup candidates. The next confirmation starts the first observation.

​
2. Prepare the configuration to confirm

The retrieved document includes display fields. Extract the fields accepted by the confirmation API, then edit confirmation.json. This example retains candidates and enables selections that were not explicitly set.

jq '.data | {
  monitoring_scope_id,
  brand: (.brand | {id, name, domain, description, industry, identity, products,
    audience: [.audience[] | {label, description, percentage, enabled: true}]}),
  competitors: [.competitors[] | {id, name, domain, selected: (if .selected == null then true else .selected end)}],
  topics: [.topics[] | {id, name, selected: (if .selected == null then true else .selected end)}],
  prompts: [.prompts[] | {id, topic_id, text, selected: (if .selected == null then true else .selected end)}],
  dimensions: (.dimensions | {engine, model_channel, region, language})
} + (if has("platform_selection") then {platform_selection} else {} end)' \
  configuration.json > confirmation.json

Check the selected prompts and models before confirming. Confirmation is a write operation that starts measurement.

orc observations configurations confirm --workspace WORKSPACE_ID \
  --stdin --json < confirmation.json > confirmation-result.json
INITIAL_BATCH_ID=$(jq -er '.data.initial_batch_id' confirmation-result.json)

Verify that initial_batch_id is returned. If it is missing, inspect the confirmation response and setup state. Do not assume measurement has started.

​
3. Wait for the first observation and read its results

orc runs batches get "$INITIAL_BATCH_ID" --workspace WORKSPACE_ID --wait --timeout 10m --json
orc runs batches get "$INITIAL_BATCH_ID" --workspace WORKSPACE_ID --json
orc runs batches results get "$INITIAL_BATCH_ID" --workspace WORKSPACE_ID --json
orc workspaces setup get --workspace WORKSPACE_ID --json

Verify that the same batch reaches completed and actual answers or results can be retrieved. Empty results, successful candidate generation, or accepted confirmation alone do not establish a completed observation.

Web Welcome uses the same generation and confirmation APIs. However, its completed_at checkpoint and initial batch completion are separate states. CLI 0.5.0 has no command to finish Welcome. If that step remains in the web app, continue in Welcome.

​
Resume after interruption or failure

Stopped stageCheck and recovery
Authentication or targetCheck orc auth status --json and the workspace ID. Do not register again.
Candidate generationRead orc observations get --workspace WORKSPACE_ID --json. Resolve the error, then repeat observations create with the same URL and workspace.
Measurement allowanceFor measurement_quota_exhausted, share the workspace ID and error with your contact. Invitation entry or retry alone does not establish recovery.
Candidate reviewReview the saved configuration.json, then confirm. Do not recreate the workspace.
Observation wait timeoutServer work continues. Resume status checks and waiting with the same INITIAL_BATCH_ID.

​
Run generation through first observation in one command

init --website is available in the published native v0.6.30 release, but is not included in CLI 0.5.0. Use the following only when orc init --help lists --website. On 0.5.0, use the stepwise commands above.

orc init --workspace WORKSPACE_ID --website https://example.com \
  --region JP --language ja --timeout 10m --json

This confirms the generated candidates and waits for the first batch. To edit before confirmation, add --no-confirm, then continue at step 2. init does not create an account or workspace.

Create a workspace · Init reference · Troubleshooting