One run, with its receipts
const url = 'http://localhost:11044/api/v1/agents/example/runs/example';const options = {method: 'GET', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url http://localhost:11044/api/v1/agents/example/runs/example \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The agent’s name
The run’s id
Responses
Section titled “Responses”The run and its receipts
One run of an agent, with a receipt for every decision made on its behalf; answered by GET /agents/{name}/runs/{id}
object
Receipts for the decisions the Gatekeeper made during the run, in the order they were made
One decision the Gatekeeper made about a call that would change something on a run’s behalf (acted, held for a person, or refused), or a person’s answer to such a request. Chained per owner by hash so an edit shows; returned with its run by GET /agents/{name}/runs/{id}
object
Name of the agent holding the work; null when no agent holds it
The holding agent’s governing signed version number when the decision was made; null when none governs it
ISO-8601 instant it was written, to the millisecond
Username of the person who approved or rejected; null when the Gatekeeper decided
act (let through), request (held for a person), refused, or a person’s approved or rejected
Business records the call’s arguments name, as field=value: a field called id, key, number, res_id or external_id, or ending Id, _id, Key, _key, Url or _url. At most 20
SHA-256 hex over everything else this receipt says, as canonical JSON with keys sorted and times as ISO-8601 text
The receipt’s id, rc_ and a UUID
SHA-256 hex of the call’s input as sent, or of the empty string when it had none
Id of the user whose chain the receipt belongs to
The hash of the receipt before it in the owner’s chain; empty for the first
Why, in words, up to 500 characters; empty when none was given
Id of the request it raised or answered; null for act and refused
What decided: authority, halted, egress, observing, never or review for the Gatekeeper, person for a person’s answer; refused when a refusal named no rule
Id of the run the decision was made for; null for a person’s answer to a request that names no run
Position in the owner’s chain, counting from 1
The verb called, as the gateway names it
Name of the routine the call was made from
The run itself: what started it, its state, timing and output
object
Name of the agent holding the work; null for a routine no agent holds
SHA-256 hex digest of that signed version; null with agentVersion
The signed version number the run went as; null when no signed version governs the agent, or no agent holds the work
For a run that answers a colleague, the names of the agents that asked, in order; empty otherwise
ISO-8601 instant the run ended; null while it is running
Why it failed or timed out, up to 1,000 characters; for a duty check, why its state is unknown. Null otherwise
The run’s id, run_ and a UUID: the {id} in GET /agents/{name}/runs/{id}
ROUTINE, REPAIR (a duty’s repair run on one violation), DUTY_CHECK, CONVERSATION or TEST
For a duty check, source warnings that left its rows sound, such as a cost note from a realm’s producer
True when the run only observed: its writes were refused and recorded as calls it would have made
RUNNING, DONE, FAILED, TIMED_OUT (including a run the appliance lost track of, closed once 30 minutes old), or SKIPPED (a scheduled firing that did not run; output says why). A duty check that could not read the world is FAILED
The last 4,000 characters it printed, the partial result when it timed out; for a skipped firing, why it did not run
Id of the user whose world the run belongs to
The agent as a principal, agent:<name>@<world>, apart from the account in runAs; null for duty checks, skipped firings and work no agent holds
For a duty check, how many violations it set out to repair; null for other runs
Ids of the approval requests it raised
Username of the account the run acted as
What its model calls cost, in US cents, keyed by model name
object
What its model calls cost in total, in US cents; 0 until the run ends
ISO-8601 instant the run started
What started it: schedule, signal:<type>, repair:<duty>, message, test, or on-demand
For a duty check, the violations it found; null for other runs and for a check that could not read the world
What ran: the routine’s name, the duty’s name for a duty check, or conversation:<agent> for a conversation
Example
{ "run": { "kind": "ROUTINE", "outcome": "RUNNING" }}No authenticated principal
A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly
object
Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own
Extra context where there is some, such as the fields a body may carry; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "code": "example", "detail": "example", "message": "example"}No such run of this agent’s in your world