# Start and cancel a run

Agent Mission Control developer docs > Bring your own agent

> The exact request AMC sends to start a run, what to return, where inputs come from, and how cancel works.

**Before you start:** An endpoint that serves `POST /runs`. See [Bring your own agent](/developers/byo-overview/).

## The start request

`POST /runs`
```json
{
  "orchestratorWorkflowId": "invoices.contoso.com/amc",
  "versionId": null,
  "inputs": {
    "invoiceId": "INV-1042",
    "ownerEmail": "sam@contoso.com"
  },
  "idempotencyKey": null
}
```

| Field | Meaning |
| --- | --- |
| `orchestratorWorkflowId` | The resource id AMC derived at registration (path segments, or host and path). Use it if one endpoint serves several workflows; otherwise ignore it. |
| `versionId` | A version id when the caller picked one, else `null`. Triggers always send `null`. |
| `inputs` | A flat map of string to string. Every value is a string: numbers and booleans arrive as text, and webhook objects or arrays arrive as JSON text. See [Declare run parameters](https://www.agentmissioncontrol.ai/developers/byo-input-contract/). |
| `idempotencyKey` | Set on scheduled fires so a retried fire doesn't start a second run. If you see a key you've already started a run for, return that run instead of starting another. |

## The response

`200 OK`
```json
{
  "orchestratorRunId": "run_5f2c0e8a41b94c55",
  "orchestratorWorkflowId": "invoices.contoso.com/amc",
  "status": "running",
  "startedAt": "2026-10-17T09:30:00.120000+00:00",
  "finishedAt": null
}
```

- Return as soon as the run is accepted, and do the work in the background. Don't hold the request open for the length of the run.
- `orchestratorRunId` is the id AMC uses on every later call. Keep it unique for the life of the endpoint.
- `startedAt` becomes the run's start time in AMC.
- Any non-terminal `status` (`running`, `pending`, `queued`) is stored as `running`, and the first poll corrects it. A terminal status (`completed`, `failed`, `cancelled`) creates the run already finished, and AMC never polls it again, so it records no tokens, cost, outcome or failure reason for that run. Return a non-terminal status and let the first poll report the ending, even for an agent that finishes synchronously.
- A non-`2xx` response, or a body AMC can't parse, fails the start: the caller gets `502` and no run is created.

## Where inputs come from

| Trigger | What arrives in `inputs` |
| --- | --- |
| **Run now** | The values the person entered. Blank fields are left out. |
| Webhook, input contract declared | Every top-level field of the JSON body, as text, whether or not you declared it. Only the reserved fields `runName` and `assigneeId` are taken by AMC and never forwarded. |
| Webhook, no input contract | One input, `payload`, holding the raw body. Reserved fields are stripped from it. |
| Schedule | No inputs, unless the workflow has default inputs set. A resource with required parameters can't be scheduled without them. |

Before any of these reaches you, AMC validates the inputs against your input contract. A start that fails validation never calls your endpoint.

## Cancel

When someone selects **Cancel run**, AMC sends `POST /runs/{id}/cancel` with an empty JSON body (`{}`) and reads a run back.

| You return | AMC does |
| --- | --- |
| `status: "cancelled"` (or `canceled`) | Ends the run as cancelled, reads its final tokens, withdraws any open intervention. |
| `completed` or `failed` | Treats the cancel as a no-op: the run had already ended, and the next poll records how. |
| A non-terminal status | Records the request and keeps polling until you report the ending. Use this for a cancel that takes time. |

- A run waiting on a person must still be cancellable.
- Return `404` for a run id you don't know.
- `cancelled` means a person asked for it. When your agent stops a run itself, report `failed` with a reason.

## Related

- [Declare run parameters](https://www.agentmissioncontrol.ai/developers/byo-input-contract/)
- [Run status and steps](https://www.agentmissioncontrol.ai/developers/byo-run-status/)
- [Errors and timeouts](https://www.agentmissioncontrol.ai/developers/byo-errors-and-timeouts/)

---
Source: https://www.agentmissioncontrol.ai/developers/byo-start-a-run/ · Last updated 2026-10-21 · Full index: https://www.agentmissioncontrol.ai/llms.txt