> ## Documentation Index > Fetch the complete documentation index at: https://docs.opentype.dev/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a run > Reads one run from stored state. Requires `runs_read`. Never calls the model, so reading a run is free. A completed run carries its `verdict` or `decision`, plus `usage` and `cost_micros`. Stored reads omit `cost_basis` and `schema_enforcement`, and a stored decision omits `model`, `stages` and the thought fields. A run that is not completed returns the run without an answer. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/runs/{run_id} openapi: 3.1.0 info: title: OpenType API version: 0.1.0 license: name: Apache-2.0 description: >- The OpenType HTTP API: decision runs on Neon 1.1, API keys, usage, quota and billing. Every `/v1` route takes `Authorization: Bearer `, where the credential is an API key (`otsk_` followed by 64 hex characters) or a console session token. Amounts are integers in micro-USD (1,000,000 = 1 US dollar). Errors share one envelope, `{"error": {"code", "message", "request_id"}}`. Stripe is named only where it hosts checkout, the billing portal and receipts. servers: - url: https://api.opentype.dev description: Production - url: https://api.opentype.dev description: Production security: - bearer: [] - bearer: [] tags: - name: runs description: Create, list, retrieve and stream runs. - name: keys description: Create, list, rotate and revoke API keys. - name: usage description: Usage rollups, the daily series, the ledger and quota. - name: billing description: Credit balance, checkout, the billing portal and auto-recharge. - name: health description: Public liveness and readiness checks. - name: router description: >- Model Router: classify a task with Neon 1.1 and pick a model from the benchmark catalog. paths: /v1/runs/{run_id}: get: tags: - runs summary: Retrieve a run description: >- Reads one run from stored state. Requires `runs_read`. Never calls the model, so reading a run is free. A completed run carries its `verdict` or `decision`, plus `usage` and `cost_micros`. Stored reads omit `cost_basis` and `schema_enforcement`, and a stored decision omits `model`, `stages` and the thought fields. A run that is not completed returns the run without an answer. operationId: get_run parameters: - name: run_id in: path description: >- `run_` followed by 32 hex characters, as the API returns it. The hyphenated form the usage routes return is also accepted. required: true schema: type: string responses: '200': description: The run as stored. content: application/json: schema: $ref: '#/components/schemas/RunResponse' '400': description: '`invalid_run_id`: not `run_` followed by a UUID.' content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '401': description: >- `missing_credentials` (no bearer credential) or `invalid_credential` (malformed, unknown or revoked). content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '403': description: >- `scope_denied`: the credential lacks `runs_read`. A session without an organization gets `no_active_organization`. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '404': description: '`run_not_found`: no run with this id in your organization.' content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '429': description: >- Your organization is sending too many requests at once. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '500': description: '`internal_error`: an unexpected failure. Report the `request_id`.' content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' '503': description: >- `database_unavailable` or `not_configured`. Also `auth_not_configured` or `trust_keys_unavailable` when credentials cannot be verified. content: application/json: schema: $ref: '#/components/schemas/RunsErrorBody' security: - bearer: [] - bearer: [] components: schemas: RunResponse: type: object description: >- A run. A completed run carries `verdict` or `decision`, never both. Absent optional fields are omitted, not `null`. Stored reads (replays, retrieve, stream, list rows) omit `cost_basis` and `schema_enforcement`; list rows also omit the answer, `usage` and cost. required: - run_id - kind - state - input_digest - replayed properties: run_id: type: string description: '`run_` followed by 32 hex characters.' kind: $ref: '#/components/schemas/RunKind' description: >- Which kind of answer this run produces: look at `verdict` or at `decision`. state: $ref: '#/components/schemas/RunStateResponse' input_digest: type: string description: 64-character hex SHA-256 of the normalized input, kind and contract. output_digest: type: - string - 'null' verdict: description: >- Completed verdict runs: your JSON document, validated against your schema. decision: oneOf: - type: 'null' - $ref: '#/components/schemas/DecisionResponse' description: The decision's answer set. Present on a completed decision run. usage: oneOf: - type: 'null' - $ref: '#/components/schemas/UsageResponse' cost_micros: type: - integer - 'null' format: int64 minimum: 0 cost_basis: oneOf: - type: 'null' - $ref: '#/components/schemas/CostBasis' description: >- Whether `cost_micros` was reported by the model service or estimated from the price list. Present exactly when `cost_micros` is. schema_enforcement: oneOf: - type: 'null' - $ref: '#/components/schemas/SchemaEnforcementResponse' description: >- What constrained the verdict. Present on a fresh verdict run; absent on a replay and on a list row. replayed: type: boolean description: >- `true` whenever the body came from storage: every replay, retrieve, stream and list row. A replay is never charged again. RunsErrorBody: type: object description: The error envelope, shared by every route. Branch on `error.code`. required: - error properties: error: $ref: '#/components/schemas/RunsErrorDetail' RunKind: type: string description: >- `decision`: probabilities over closed answer sets. `verdict`: one JSON document validated against your schema. enum: - verdict - decision RunStateResponse: type: string enum: - pending - running - completed - failed DecisionResponse: type: object description: A decision's answers. required: - answers - draws - read properties: answers: description: >- One answer per question, keyed by your question ids. Shapes by `type`: `noul` has `probability`, which is P(yes); `choice` has `choice`, `probabilities` keyed by option name, and `confidence`; `score` has `score` (the expected 0-based level index), `legend`, `probabilities` keyed by index, and `confidence`; `skipped` has `because` (`question`, `answered` when known, `required`) when an `ask_if` failed. Any answer may carry `label_mass` and `answered_within_labels`. Every probability and confidence is between 0 and 1. draws: type: integer format: int32 description: Reads averaged. minimum: 0 read: $ref: '#/components/schemas/DecisionReadResponse' description: >- What constrained the answers. Only `slot_constrained` is produced today. model: type: - string - 'null' description: 'Live responses only. The model that served the run: `neon-1.1`.' example: neon-1.1 stages: type: array items: type: array items: type: string description: >- Live responses only. Question ids per stage, in the order the stages ran. thought_tokens: type: - integer - 'null' format: int32 description: >- Live responses only, when thought tokens were generated. The thought text is never returned. minimum: 0 thought_closed: type: - boolean - 'null' UsageResponse: type: object description: Tokens the run used. required: - input_tokens - output_tokens properties: input_tokens: type: integer format: int64 minimum: 0 output_tokens: type: integer format: int64 minimum: 0 CostBasis: type: string description: >- `provider_reported`: the usage the model reported. `estimated`: the pre-call estimate at list prices. enum: - provider_reported - estimated SchemaEnforcementResponse: type: string description: >- `unconstrained`: only the server's own validation bound the answer. `requested`: the schema was offered to the model but did not bind it. `forced`: the model was compelled into the schema slot, unchecked upstream. `enforced`: decoding was constrained to the schema. Every returned verdict passed validation, whatever this says. enum: - unconstrained - requested - forced - enforced RunsErrorDetail: type: object required: - code - message - request_id properties: code: type: string description: Stable snake_case code. The only field to branch on. message: type: string request_id: type: string violations: type: array items: type: string description: >- Only on `verdict_schema_violation`: up to 10 JSON Pointers into the rejected document. DecisionReadResponse: type: string description: >- What constrained a decision's answers: `slot_constrained` when the model could only answer inside the closed answer set, `reconstructed` when the answers were read back from its output. enum: - slot_constrained - reconstructed securitySchemes: bearer: type: http scheme: bearer description: An API key (otsk_ + 64 hex) or a console session token. ````