Running a job

Everything the dashboard can do with a job, the CLI and API can do too. The examples below lead with the CLI; every command has a matching REST endpoint under /v1/autoimprove/job.

Create a job

roark autoimprove job create \
  --agent-id "$AGENT_ID" \
  --objective-metric-definition-id "$METRIC_ID" \
  --objective-label "Consent collection should pass" \
  --target-value 90

curl -X POST https://api.roark.ai/v1/autoimprove/job \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'"$AGENT_ID"'",
    "objectiveMetricDefinitionId": "'"$METRIC_ID"'",
    "objectiveLabel": "Consent collection should pass",
    "targetValue": 90
  }'

Returns 201 with the job, already RUNNING. Useful optional fields:

Field	What it does
`stagingAgentId`	Stage changes on an existing agent of yours instead of the default shadow clone. Must differ from `agentId` and share its provider.
`customerIntegrationId`	Pin the provider integration whose credentials Roark uses. Defaults to the project’s active integration for the agent’s provider. The integration must have agent config writes enabled.
`validationRunPlanId`	Bring your own simulation run plan instead of letting Roark author a suite.
`maxIterations`, `maxSimCalls`	Tighten or widen the hard budgets (defaults 10 and 200).

One live job per agent: creating a second returns 409.

The job starts spending real resources immediately: a shadow agent and phone number in your provider account, and simulated phone calls that bill like any other simulation. The budgets cap the total.

Watch it work

roark autoimprove job get <job-id>
roark autoimprove job list

curl https://api.roark.ai/v1/autoimprove/job/$JOB_ID \
  -H "Authorization: Bearer $ROARK_API_KEY"

The single-job response includes logEntries, the full worklog oldest-first. The kinds worth watching for:

Kind	Meaning
`SETUP`	The staging checklist: shadow ready, number assigned, reachable.
`SUITE`	Roark authored its validation scenarios.
`CHANGE`	A configuration change applied to staging (`configPushId` links the audited diff).
`VALIDATION`	A batch of test calls settled: `trialCount`, `passRateBefore`, `passRateAfter`.
`QUESTION`	Roark is blocked on you; `questionOptions` carries its suggested answers.
`VERDICT`	The conclusion and why.
`STATUS`	Everything else it wants you to know, including cleanup confirmations.

Poll the job until status leaves RUNNING. The workingMemory field is Roark’s own running notes; finalReport is its closing story once concluded.

Steer and answer

Send guidance any time the job is live; it binds Roark’s next decision:

roark autoimprove job guidance send <job-id> \
  --text "Keep the current voice; focus on the closing confirmation."

curl -X POST https://api.roark.ai/v1/autoimprove/job/$JOB_ID/guidance \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Keep the current voice; focus on the closing confirmation."}'

When status is NEEDS_INPUT, answer the open question (free text or one of the offered options). Unanswered questions proceed with Roark’s stated default after 24 hours:

roark autoimprove job answer <job-id> --text "Prefer accuracy over latency"

Answering a job that is not waiting returns 409.

Promote or dismiss

A verified job (AWAITING_PROMOTE) holds its staged changes until you decide:

roark autoimprove job promote <job-id>
roark autoimprove job dismiss <job-id>

curl -X POST https://api.roark.ai/v1/autoimprove/job/$JOB_ID/promote \
  -H "Authorization: Bearer $ROARK_API_KEY"

Promote applies the verified operations to the production agent through the same audited funnel, with a pre-promote snapshot for rollback, then cleans up the staging resources. Dismiss discards everything; production is never touched. Both return 409 unless the job is awaiting review.

Cancel

roark autoimprove job cancel <job-id>

Stops a live job. Cleanup is automatic: the shadow agent, its phone number, and the authored suite are removed. Production is never changed by a cancel.

Cross-tenant and unknown job ids are indistinguishable: both return 404.

Getting Started

Simulations

Observability

Metrics

Config as Code

Autoimprove

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Create a job

Watch it work

Steer and answer

Promote or dismiss

Cancel

​Create a job

​Watch it work

​Steer and answer

​Promote or dismiss

​Cancel

Create a job

Watch it work

Steer and answer

Promote or dismiss

Cancel