Runs

14 operations. {prefix} is the route prefix passed to MapAgentPrism; the template uses /agentprism.

GET {prefix}/api/runs

Operation ID: AgentPrismListRuns

Lists runs from newest to oldest.

By default, ONLY root runs are returned. To also see child runs, use ‘includeChildren=true’; pass ‘rootRunId’ for an entire tree, or ‘parentRunId’ for the direct children of a run. ‘userId’ narrows the list to one user’s runs, and ‘label’ takes a ‘key:value’ pair (‘label=team:payments’); a bare ‘label=team’ matches any value of that key. Both dimensions are recorded from the server-side IRunAttributionContext, never from the run request body.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
agentName	query	no	string	—
status	query	no	RunStatus	—
kind	query	no	RunKind	—
sessionId	query	no	string	—
errorType	query	no	string	—
userId	query	no	string	—
label	query	no	string	—
startedAfter	query	no	string (date-time)	—
includeChildren	query	no	boolean	—
parentRunId	query	no	string (uuid)	—
rootRunId	query	no	string (uuid)	—
skip	query	no	integer (int32)	pattern `^-?(?:0\
take	query	no	integer (int32)	pattern `^-?(?:0\

Response	Body	Headers
200 OK	application/json → array of RunRecord	—

GET {prefix}/api/runs/{a}/compare/{b}

Operation ID: AgentPrismCompareRuns

Returns the summaries of two runs side by side.

The diff is NOT computed on the server; the endpoint returns the two summaries and the UI shows the comparison — the same pattern as the agent definition version diff.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
a	path	yes	string (uuid)	—
b	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → RunComparisonResponse	—

GET {prefix}/api/runs/{runId}

Operation ID: AgentPrismGetRun

Returns the summary of a single run.

The summary carries status, timings, token counts, and — when pricing is configured — cost; it does not carry the conversation. Read the messages from the events endpoint, and the recorded input from the input endpoint. A run row is written when the run starts, so a run that is still going is readable here with a non-terminal status.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → RunRecord	—

POST {prefix}/api/runs/{runId}/cancel

Operation ID: AgentPrismCancelRun

Requests cancellation of a running run.

202 only reports that cancellation was REQUESTED; the final status is read from ‘GET /api/runs/{id}’. Returns 409 if the run is not executing on this instance (a different instance, or a restarted process). Canceling a root run also stops every child run in the tree; canceling a child run on its own does not affect the root.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
202 Accepted	application/json → RunRecord	—

GET {prefix}/api/runs/{runId}/events

Operation ID: AgentPrismStreamRunEvents

Streams a run’s events over SSE; live and historical use the same path.

If the connection drops, the client resumes from its last sequence number using the ‘Last-Event-ID’ header. If the run is still in progress, the stream stays open until it completes.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	—	—

GET {prefix}/api/runs/{runId}/feedback

Operation ID: AgentPrismListRunFeedback

Lists all scores for a run.

Both human scores and scores written by automatic evaluators appear in one list; the source is a field on each entry, not a separate endpoint. A run belonging to another tenant is reported as 404 rather than 403, so the API does not confirm that the run exists. A run with no scores returns an empty list, not 404.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → array of RunScore	—

POST {prefix}/api/runs/{runId}/feedback

Operation ID: AgentPrismSaveRunFeedback

Writes a score for a run or for a single message.

When the same author scores the same target (run or message) a second time, the row is UPDATED, not a new row opened. If ‘messageId’ is left blank, the score applies to the whole run.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Request body (required):

• application/json → RunFeedbackRequest

Response	Body	Headers
200 OK	application/json → RunScore	—

DELETE {prefix}/api/runs/{runId}/feedback/{scoreId}

Operation ID: AgentPrismDeleteRunFeedback

Deletes a score.

The deletion is recorded in the audit trail, so removing a score is itself traceable. The run must belong to the calling tenant; otherwise the response is 404. An unknown score id also returns 404, so repeating the call is not idempotent. Aggregate statistics computed from scores are recalculated on the next read rather than adjusted here.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—
scoreId	path	yes	string (uuid)	—

Response	Body	Headers
204 No Content	—	—

GET {prefix}/api/runs/{runId}/input

Operation ID: AgentPrismGetRunInput

Returns the recorded input messages for a run.

Returns 404 for a run that started while input recording was disabled (AgentPrism:RunRecording:RecordRunInput = false), or that was deleted by a retention policy; such a run cannot be replayed.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → RunInputResponse	—

POST {prefix}/api/runs/{runId}/replay

Operation ID: AgentPrismReplayRun

Starts a new run with recorded input.

The input is preserved, the conditions change: ‘agentVersion’, ‘modelId’, and ‘toolMode’. The default ‘toolMode’ value is ‘ReplayTools’, and NO tool actually runs — recorded results are replayed. Replaying a call with no recorded result STOPS the replay and returns 422. ‘LiveTools’ ACTUALLY runs tools, produces side effects, requires the Admin role, and returns 409 if a tool requires approval. Replay is sessionless: if the source run belongs to a session, only that TURN’s input is replayed; the conversation history is not carried over.

Authorization: bearer authentication; Operator role policy when that policy is registered; RunsWrite API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Request body (required):

• application/json → RunReplayRequest

Response	Body	Headers
200 OK	application/json → RunReplayResponse	—
400 Bad Request	application/problem+json → ProblemDetails	—
403 Forbidden	application/problem+json → ProblemDetails	—
404 Not Found	application/problem+json → ProblemDetails	—
409 Conflict	application/problem+json → ProblemDetails	—
422 Unprocessable Entity	application/problem+json → ProblemDetails	—
502 Bad Gateway	application/problem+json → ProblemDetails	—

GET {prefix}/api/runs/{runId}/tools

Operation ID: AgentPrismListRunToolInvocations

Lists a run’s tool calls in chronological order.

Duration is measured only for streaming runs: in a non-streaming run all messages arrive at once, so the true duration between call and result cannot be read.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → array of ToolInvocationRecord	—

GET {prefix}/api/runs/{runId}/trace

Operation ID: AgentPrismGetRunTrace

Returns a run’s span tree.

Spans are written with sampling. Spans for failed runs are always recorded by default; successes are recorded at a configurable rate.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → RunTrace	—

GET {prefix}/api/runs/{runId}/tree

Operation ID: AgentPrismGetRunTree

Returns the entire tree a run belongs to, starting from the root.

The tree is always resolved from the ROOT, whichever member is asked for: a request naming a child run still returns the whole tree, because without the sibling branches a client cannot tell where in the tree that run sits. Each entry carries its parent, so the shape is rebuilt on the client. At most 200 runs are returned; a tree larger than that is truncated rather than paged.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
runId	path	yes	string (uuid)	—

Response	Body	Headers
200 OK	application/json → array of RunRecord	—

GET {prefix}/api/tools/usage

Operation ID: AgentPrismToolUsage

Returns call count, error rate, and average duration per tool.

The summary is computed by the store itself; it is not a paginated subset.

Authorization: bearer authentication; Reader role policy when that policy is registered; RunsRead API-key scope.

Parameter	In	Required	Type	Description and rules
startedAfter	query	no	string (date-time)	—
maxTools	query	no	integer (int32)	pattern `^-?(?:0\

Response	Body	Headers
200 OK	application/json → array of ToolUsage	—