​

Start monitoring a client brand

Confirm the client, workspace owner, brand, prompts, and capacity. Keep client scopes distinct and verify the first observation.

Create a client or pitch workspace from one account, then review its brand, prompts, and first observations.

Use an authenticated account with permission to manage client workspaces. Keep an organization-scoped write key and a human agency operator with Workspace access available. Confirm the client scope before writes or observation runs.

Use the organization key for organization workspace listing, capacity, creation, and the control-plane operation that assigns an existing organization member to one workspace. The organization key is not a Workspace data credential. If orc whoami runs with the organization key, it reports principalType: api_key and an apikey:... ID; never use that synthetic ID as the human --user-id.

Authenticate the permitted human agency operator in a separate named profile. Use the data.user.id returned by that profile's orc whoami --json as YOUR_OPERATOR_USER_ID. Then run this with the organization-key profile to grant exactly one active organization member access to the target workspace:

The operation verifies that the target workspace belongs to the organization bound to the key and that the user is an active organization member. An X-Workspace-ID sent before the grant does not grant access. In a browser, POST /v1/workspaces/current/selection likewise validates an active human membership and saves a preference; it does not create membership. In the CLI, use orc workspace use in the operator profile or pass --workspace on each data command after the grant.

Keep organization control-plane and Workspace data operations on separate profiles. workspaces quotas get reads organization capacity and must use the organization key; do not run it with a workspace-scoped key. If automation needs a read key, create it from the human operator profile after the grant with orc api-keys create --scope workspace --workspace YOUR_CLIENT_WORKSPACE_ID --type read_only --output NEW_PRIVATE_KEY_FILE. There is no path that turns an organization key or organization-scoped service-account key into Workspace data access.

Replace placeholders with IDs returned by earlier operations. Review each result before you continue; this block is not an unattended script.

Reuse an existing client workspace when present. Specify its ID on every operation to keep client scopes separate.

Use --purpose client for ongoing client monitoring. For a proposal, create a pitch workspace in your agency organization instead. Run only the creation command for the purpose you need:

Use the returned pitch workspace ID in the remaining commands. Pitch creation requires both monthly pitch_workspaces and concurrent active_pitch_workspaces capacity. Check remaining and unlimited before creation. Read the created workspace's expires_at; pitch workspaces expire seven days after creation. Creating another client's workspace requires a new name, brand, and idempotency key.

Pass the client brand, country, and language to workspaces create. A workspace created with an organization key does not automatically receive a human membership, so run the members create operation from the previous section with the returned ID. After the grant succeeds, run orc workspace use YOUR_CLIENT_WORKSPACE_ID in the operator profile. workspaces setup get returns the current setup state. Run it again while setup is in progress, and inspect the initial batch status and any blocker before reading reports. With npm CLI 0.6.0 (the beta tag) or later, add --wait to wait for completion.

Set YOUR_OPERATOR_USER_ID to the human user ID of an organization member. Do not use the organization key's synthetic ID. After the grant, confirm that orc workspace use or --workspace in the operator profile succeeds before reading Workspace data. If permission is denied, check the operator's organization membership and role instead of retrying the grant with a different organization key.

Pass the same workspace ID to brands list and prompts list. Confirm that the results do not contain another client's brand or prompts. A new workspace may temporarily return empty lists while setup is processing.

Pass the same workspace ID to reports visibility get. If the report has no data, inspect the result from workspaces setup get for a failed initial batch or a blocker.

The pitch workspace used for verification can recover through the same members create → operator workspace use → setup/brands/prompts/report read sequence after it has been paused. Do not attach an organization key's Workspace header or create another organization key to read it. To resume observation, the human operator with confirmed access can run orc workspaces resume YOUR_PITCH_WORKSPACE_ID --idempotency-key YOUR_RESUME_IDEMPOTENCY_KEY --yes --json.

If you do not receive the workspaces create response, resend the same request with the same idempotency key. This does not duplicate the client or prompts. If waiting stops, run workspaces setup get again with the same workspace ID.

After a successful proposal, convert the same pitch workspace to ongoing monitoring to retain its history. Use npm CLI 0.6.0 (the beta tag) or later for that conversion. Check each client’s usage limits before adding another workspace.

All workflows

If a failure remains, report it and verify the fix, including this workflow and the failed step.