Skip to the content

Read a run of a decision corpus

GET /v1/agents/{agent_id}/decision-corpora/{corpus_id}/runs/{run_id}

Property	Value
Operation	`get_decision_run`
Group	Decision corpora
Scope	`agents:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A metadata read; a run holds numbers only.
Released in	1.58.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Answers the run with its status and, once completed, precision and recall per label over the sweep with the proposed thresholds (1.58.0).

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the agents:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl "$VOCAL_API/v1/agents/agt_.../decision-corpora/dcp_.../runs/dcr_..." \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/agents/agt_.../decision-corpora/dcp_.../runs/dcr_...`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/agents/agt_.../decision-corpora/dcp_.../runs/dcr_...",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`agent_id`	path	AgentId	yes	The id of an Agent: `agt_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`corpus_id`	path	DecisionCorpusId	yes	The id of a decision corpus: `dcp_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`run_id`	path	DecisionRunId	yes	The id of an evaluation run of a decision corpus: `dcr_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	DecisionRun
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`404`	`application/json`	ErrorEnvelope	`not_found`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is DecisionRun.

Field	Type	Required	Description
`agent_id`	AgentId	yes
`agent_version`	integer	yes	The active version whose chain ran.
`cases`	integer	yes	The cases sent.
`completed_at`	Timestamp or null	yes
`corpus_id`	DecisionCorpusId	yes
`corpus_version`	integer	yes
`created_at`	Timestamp	yes
`created_by`	ActorRef	yes
`error_code`	string or null	yes	Why a `failed` run failed, such as `provider_unavailable`; null otherwise.
`id`	DecisionRunId	yes
`job_id`	JobId	yes
`model_version`	string	yes
`object`	`"decision_run"`	yes
`precision_target`	number	yes	The precision a proposed threshold must meet, 0.9 when omitted (a target).
`provider`	ProviderId	yes
`question_set`	QuestionSetKey	yes
`results`	array of DecisionQuestionResult	yes	Per question, once `completed`; empty before.
`status`	DecisionRunStatus	yes
`usage`	DecisionRunUsage or null	no	What the run used (1.59.0), once its result landed, completed or failed; null while it is `queued` or `running`. Absent from an api before 1.59.0, which a reader treats as null.