> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Running a job

> The full Autoimprove lifecycle over the CLI and API: create a job, watch the worklog, steer and answer, then promote or dismiss

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

<CodeGroup>
  ```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  roark autoimprove job create \
    --agent-id "$AGENT_ID" \
    --objective-metric-definition-id "$METRIC_ID" \
    --objective-label "Consent collection should pass" \
    --target-value 90
  ```

  ```bash API theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  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
    }'
  ```
</CodeGroup>

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 50 and 200).                                                                                                                                 |

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

<Warning>
  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.
</Warning>

## Watch it work

<CodeGroup>
  ```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  roark autoimprove job get <job-id>
  roark autoimprove job list
  ```

  ```bash API theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  curl https://api.roark.ai/v1/autoimprove/job/$JOB_ID \
    -H "Authorization: Bearer $ROARK_API_KEY"
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  roark autoimprove job guidance send <job-id> \
    --text "Keep the current voice; focus on the closing confirmation."
  ```

  ```bash API theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  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."}'
  ```
</CodeGroup>

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:

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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:

<CodeGroup>
  ```bash CLI theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  roark autoimprove job promote <job-id>
  roark autoimprove job dismiss <job-id>
  ```

  ```bash API theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
  curl -X POST https://api.roark.ai/v1/autoimprove/job/$JOB_ID/promote \
    -H "Authorization: Bearer $ROARK_API_KEY"
  ```
</CodeGroup>

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

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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.

<Note>
  Cross-tenant and unknown job ids are indistinguishable: both return `404`.
</Note>