Runs and External Evidence
Follow asynchronous Runs, interpret their outcome, and retrieve safe, short-lived evidence.
run.trigger queues work and returns immediately. Follow each returned runId with run.get; retrieve run.evidence when you need the facts behind an outcome.
Follow a Run with a cursor
The first run.get call needs only the Run id:
1{2 "runId": "jh7examplerunid"3}Save its numeric cursor. To wait for a change, send the same Run id, that cursor, and waitMs:
1{2 "runId": "jh7examplerunid",3 "cursor": 42,4 "waitMs": 250005}The HTTP adapter polls once per second and returns when the cursor increases, the Run reaches a terminal status, or the wait expires. waitMs is bounded to 0–25000 milliseconds; values above the cap are clamped to 25000. A response with timedOut: true is successful data meaning that nothing changed during the window. Repeat with the same cursor or stop waiting; do not treat it as an API error.
The response also contains progress, per-step state, whether evidence is available, and next. next is advice, never authority: decide from status, verdict, validity, progress, and steps.
Status, verdict, and validity
These are separate fields. status is execution state, verdict is the customer-facing outcome when one exists, and validity says whether the Run could be evaluated.
status | verdict | validity | Meaning |
|---|---|---|---|
queued | Omitted | not_evaluated | Waiting to start. |
running | Omitted | not_evaluated | Execution is in progress. |
retrying | Omitted | not_evaluated | Execution is retrying and has no final outcome. |
passing | passed | valid | The Run completed with a passing verdict. |
failed | failed | valid | The Run completed and demonstrated a failure. |
unverified | unverified | valid | The Run completed without proving pass or fail. |
canceled | unverified | valid | The Run was canceled and has no verified outcome. |
invalid | unverified | invalid | The Run could not produce a valid evaluation. |
passing, failed, unverified, canceled, and invalid are terminal for long-polling. The response's next is wait for queued, running, or retrying; retry for invalid; evidence for failed, unverified, or a passing but flaky Run; otherwise it is none.
External Evidence
Call POST /api/v1/run.evidence with runId and, optionally, a numeric step filter. The response contains the Run's status, verdict, and validity plus customer-safe evidence for each included step:
- step index, authored action and optional target;
passed,failed, orskippedstep status and a reason;- observed facts, the authored expectation, verdict source, and whether the postcondition was proven;
- recovery count and a diagnosis with category and suggested action;
- neutralized action names and targets;
- screenshot, frame, or video links with expiry times;
- step duration.
External Evidence never includes model or provider identity, prompts, token or cost figures, raw runner errors, internal tool names, runner internals, or raw UI trees.
Signed media links
Each media item returned by run.evidence has a signed url and expiresAt. The URL calls:
GET /api/v1/evidence/<id>?kind=<screenshot|frame|video>&exp=<epoch-ms>&sig=<signature>The link is valid for 15 minutes and does not require a bearer credential because the signature carries its short-lived authorization. A valid request redirects with 302 to the temporary storage URL. An invalid or expired signature returns 403; missing media returns 404. Call run.evidence again for fresh links rather than editing the query parameters.
Environment values and secrets
Environment targets can store named runtime values. environment.list and environment.get return only runtimeValueNames; they never return values. In a UI fill step, refer to one by name:
1{2 "action": "fill",3 "target": "Password",4 "valueSpec": {5 "kind": "environment",6 "variable": "LOGIN_PASSWORD"7 }8}For a referenced secret, Autonomy sends the value to the runner over the authenticated TLS claim channel immediately before execution. The runner holds it in memory only. The model sees an {{env.LOGIN_PASSWORD}} placeholder, and the harness substitutes the value only when dispatching the fill action. The value is added to redaction for traces, diagnoses, logs, External Evidence, and playbook memory; it is never written to disk or returned by a runner route.
If a referenced value is missing, the Run fails closed before steps start with an environment diagnosis. The next-generation runner supports this substitution; the stable runner refuses to claim Runs whose steps reference Environment values rather than executing without the secret.
API-target runtime values are separate: run.trigger can carry them in targets.api.runtimeValues, while API credential bindings continue to resolve {{env.NAME}} from the runner host environment.