Browse the docs

Start and cancel a run

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

Before you startAn endpoint that serves `POST /runs`. See [Bring your own agent](/developers/byo-overview/).View as Markdown

The start request

POST /runs
{
  "orchestratorWorkflowId": "invoices.contoso.com/amc",
  "versionId": null,
  "inputs": {
    "invoiceId": "INV-1042",
    "ownerEmail": "sam@contoso.com"
  },
  "idempotencyKey": null
}
FieldMeaning
orchestratorWorkflowIdThe resource id AMC derived at registration (path segments, or host and path). Use it if one endpoint serves several workflows; otherwise ignore it.
versionIdA version id when the caller picked one, else null. Triggers always send null.
inputsA 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.
idempotencyKeySet 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
{
  "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

TriggerWhat arrives in `inputs`
Run nowThe values the person entered. Blank fields are left out.
Webhook, input contract declaredEvery 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 contractOne input, payload, holding the raw body. Reserved fields are stripped from it.
ScheduleNo 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 returnAMC does
status: "cancelled" (or canceled)Ends the run as cancelled, reads its final tokens, withdraws any open intervention.
completed or failedTreats the cancel as a no-op: the run had already ended, and the next poll records how.
A non-terminal statusRecords 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

Last updated 2026-10-21