> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get one evaluation record

> One evaluation of any document in the namespace, any incarnation and
any judgment, with its compiled context and the engine's raw response
(§6.7). Shadow evaluations are included, marked `shadow`. Unlike a
document's history, it is found by id alone.




## OpenAPI

````yaml /api-reference/openapi.yaml get /namespaces/{ns}/evaluations/{id}
openapi: 3.1.0
info:
  title: Vainona API
  version: '1'
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  description: |
    The `/v1` contract from main spec §6. It is locked: changes within `/v1`
    are additive only, and anything breaking is `/v2`.

    - **Base URL.** `https://api.vainona.ai/v1`.
    - **Evolution.** Response objects may gain fields and enums may gain values.
      Clients must ignore what they do not know. Request objects reject unknown
      fields.
    - **Path segments.** Namespace names (`{ns}`) and document ids (`{id}`) may
      contain `/`. Send it percent-encoded as `%2F`, so that
      `acme/prod/tenant_123` is `acme%2Fprod%2Ftenant_123`.
    - **Templates (v1.5).** The judgment routes also take a namespace prefix
      ending in `/*`, such as `acme%2Fprod%2F*`. A judgment created there is a
      template: every namespace under the prefix inherits it, including ones
      created later. The most specific matching prefix wins (§7.7).
    - **Thresholds are settings (v1.5).** Named thresholds belong to the
      judgment, not to a version. They are evaluated at read time against the
      raw fields, so a change applies at once to every answer, with no
      recompute and no new version (§6.5).
    - **Entity judgments (entities, E1).** A judgment can read the documents
      that point at the judged one, through `context.related`, and apply only
      to documents matching `applies_to` (§6.5.2). Its answers carry a
      `watermark`, and creating one that runs `on_change` returns a replay
      estimate of its monthly cost until you confirm (§6.9).
    - **Referenced documents (entities, E3a).** A relation can also read the
      one document the judged document points at, through
      `join: {theirs: "id", mine: "attributes.<name>"}`. A change to what the
      relation renders of that document re-judges the judged documents that
      point at it and are inside `freshness.fanout.scope`: a fan-out. A large
      fan-out is a `fanout` job that waits for confirm (§6.5.2, §6.9).
    - **Idempotency.** Every write operation is idempotent by construction.
      `Idempotency-Key` is accepted on every mutating route and, while the node
      still caches the original response, returns it verbatim.
    - **Errors.** Every error is the `Error` envelope; the HTTP status follows
      the code (see each response).
    - **Rate limits.** Every response carries `X-RateLimit-Limit` and
      `X-RateLimit-Remaining`; a `rate_limited` response adds `Retry-After`,
      except a daily allowance that is used up, which says when it renews in
      `details.resets_at` instead.
    - **Usage.** Every response that bills carries `usage`. Judging is billed in
      engine-neutral judgment units: one judgment answered, per started 1,000
      tokens of its compiled context and its question together, at least 1
      (§9). No response ever carries an
      engine's price.
servers:
  - url: https://api.vainona.ai/v1
security:
  - apiKey: []
tags:
  - name: Namespaces
    description: Namespaces, their settings and cache warming (§6.2, §6.11).
  - name: Documents
    description: Writes, point reads and queries (§6.3 to §6.8).
  - name: Judgments
    description: >-
      Judgment definitions, versions, settings, activation, backfill and
      template detach (§6.5, §6.9, §7.7).
  - name: Outcomes and calibration
    description: |
      Post what actually happened to judged documents, and read how well answers
      match it: the calibration report, calibrated answers and threshold
      recommendations (§6.10). See [calibration](/concepts/calibration).
  - name: Jobs
    description: >-
      Backfill, shadow, periodic, deletion, reference index and fan-out jobs
      (§6.2, §6.9, §7.10.5).
  - name: Engines
    description: The engine registry (§6.5, §7.4.5).
paths:
  /namespaces/{ns}/evaluations/{id}:
    parameters:
      - $ref: '#/components/parameters/Namespace'
      - name: id
        in: path
        required: true
        description: The evaluation id, `ev_` and a ULID.
        schema:
          type: string
          pattern: ^ev_[0-9a-z]{26}$
    get:
      tags:
        - Documents
      summary: Get one evaluation record
      description: |
        One evaluation of any document in the namespace, any incarnation and
        any judgment, with its compiled context and the engine's raw response
        (§6.7). Shadow evaluations are included, marked `shadow`. Unlike a
        document's history, it is found by id alone.
      operationId: getEvaluation
      responses:
        '200':
          description: The evaluation, with `context` and `raw`.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/TooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
components:
  parameters:
    Namespace:
      name: ns
      in: path
      required: true
      description: The namespace name, with any `/` sent as `%2F`.
      schema:
        $ref: '#/components/schemas/NamespaceName'
  headers:
    RateLimitLimit:
      description: Requests allowed per second for this key.
      schema:
        type: integer
        minimum: 0
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        minimum: 0
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 0
  schemas:
    Evaluation:
      type: object
      description: An immutable record of one computation.
      required:
        - id
        - document_id
        - revision
        - incarnation
        - judgment
        - judgment_version
        - engine
        - engine_version
        - context_hash
        - context_tokens
        - context_truncated
        - output
        - status
        - error
        - shadow
        - created_at
      properties:
        id:
          type: string
        document_id:
          $ref: '#/components/schemas/DocumentId'
        revision:
          $ref: '#/components/schemas/Revision'
        incarnation:
          $ref: '#/components/schemas/Revision'
        judgment:
          $ref: '#/components/schemas/Name'
        judgment_version:
          $ref: '#/components/schemas/JudgmentVersionNumber'
        engine:
          type: string
        engine_version:
          type: string
        context_hash:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
        context_tokens:
          type: integer
          minimum: 0
        context_truncated:
          type: boolean
        output:
          description: The engine's numbers. Null when the evaluation failed.
          oneOf:
            - $ref: '#/components/schemas/EvaluationOutput'
            - type: 'null'
        status:
          type: string
          enum:
            - success
            - failed
        error:
          description: Why the evaluation failed. Null on success.
          oneOf:
            - $ref: '#/components/schemas/EvaluationError'
            - type: 'null'
        shadow:
          type: boolean
          description: >-
            True for shadow evaluations from activation reports, which never
            produce answers.
        created_at:
          $ref: '#/components/schemas/Timestamp'
        latency_ms:
          type: integer
          minimum: 0
          description: >-
            How long the engine request that produced it took, retries excluded.
            Absent for evaluations recorded before it was measured.
        watermark:
          $ref: '#/components/schemas/Revision'
          description: >-
            Entity judgments only (entities, E1, §6.7). The log position the
            context was read at.
        related_documents:
          type: array
          description: |
            Entity judgments only (entities, E1, §6.7), with
            `include=history,context` or from `GET .../evaluations/{id}`.
            Every related document the context read, rendered or aggregated,
            with the revision it was read at.
          items:
            $ref: '#/components/schemas/RelatedDocument'
        context:
          type: object
          description: With `include=history,context`, the compiled context the engine saw.
        raw:
          description: >-
            With `include=history,raw`, the engine's raw response. It never
            carries the engine's token counts (§6.1).
    NamespaceName:
      type: string
      description: >-
        Up to 256 bytes. `/` separates levels of the hierarchy, as in
        `acme/prod/tenant_123`.
      pattern: ^[A-Za-z0-9._:/-]+$
      minLength: 1
      maxLength: 256
    DocumentId:
      type: string
      description: Up to 128 bytes.
      pattern: ^[A-Za-z0-9._:/-]+$
      minLength: 1
      maxLength: 128
    Revision:
      type: integer
      format: int64
      minimum: 0
    Name:
      type: string
      description: >-
        A judgment, attribute or threshold name. Names are path segments in
        field references, so they never contain `.`.
      pattern: ^[A-Za-z0-9_-]+$
      minLength: 1
      maxLength: 128
    JudgmentVersionNumber:
      type: integer
      format: int32
      minimum: 1
    EvaluationOutput:
      type: object
      description: >-
        The engine's raw numbers. A composite judgment's evaluation has `parts`,
        each part's `p`; its combined `p` is computed when answers are read
        (§6.5.1).
      properties:
        p:
          $ref: '#/components/schemas/Probability'
        value:
          type: string
        dist:
          $ref: '#/components/schemas/Distribution'
        escape_p:
          $ref: '#/components/schemas/Probability'
        score:
          type: number
        parts:
          type: object
          propertyNames:
            $ref: '#/components/schemas/Name'
          additionalProperties:
            $ref: '#/components/schemas/Probability'
        features:
          $ref: '#/components/schemas/FeatureValues'
    EvaluationError:
      type: object
      required:
        - class
        - message
      properties:
        class:
          type: string
          enum:
            - retryable
            - terminal
        message:
          type: string
    Timestamp:
      type: string
      format: date-time
      description: RFC 3339, UTC.
    RelatedDocument:
      type: object
      required:
        - relation
        - document_id
        - revision
      properties:
        relation:
          $ref: '#/components/schemas/Name'
        document_id:
          $ref: '#/components/schemas/DocumentId'
        revision:
          $ref: '#/components/schemas/Revision'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
            details:
              type: object
              description: >-
                Code-specific detail, such as the scan estimate on a refused
                query. Every `internal` error has `request_id`.
    Probability:
      type: number
      minimum: 0
      maximum: 1
    Distribution:
      type: object
      description: Probability per option or level value. Sums to 1.
      additionalProperties:
        $ref: '#/components/schemas/Probability'
    FeatureValues:
      type: object
      description: >-
        Composite judgments with features only (entities, E1, §6.5.1). Each
        feature's raw value, as rendered in the context; null when missing.
      propertyNames:
        $ref: '#/components/schemas/FeatureRef'
      additionalProperties:
        type:
          - number
          - 'null'
    ErrorCode:
      type: string
      description: |
        HTTP status by code: `invalid_request` 400, `unauthorized` 401,
        `budget_exceeded` 402, `forbidden` 403, `not_found` 404, `conflict` 409,
        `too_large` 413, `engine_version_unavailable` 422,
        `insufficient_labels` 422, `rate_limited` 429, `internal` 500,
        `engine_unavailable` 503.
      enum:
        - invalid_request
        - unauthorized
        - forbidden
        - not_found
        - conflict
        - too_large
        - rate_limited
        - budget_exceeded
        - engine_unavailable
        - engine_version_unavailable
        - insufficient_labels
        - internal
  responses:
    InvalidRequest:
      description: '`invalid_request`: the request is malformed or breaks a rule of §6.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: '`unauthorized`: the key is missing, unknown or revoked.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: '`forbidden`: the key''s role or namespace prefix does not allow this.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: '`not_found`: the namespace, document, judgment or job does not exist.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        `conflict`: the namespace is being deleted, an object a read needs was
        compacted away and the read (or the query, without its cursor) must
        restart (§7.5.11), or the judgment is inherited from a template and this
        namespace cannot create, activate or delete it (§7.7).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooLarge:
      description: >-
        `too_large`: the request body (on any route), a document, or the
        estimated query scan is over its limit. `details` carries the estimate
        for queries. It also answers a write that would take
        `default/quickstart` past its size cap (10,000 documents or 100 MB),
        with `details.max_documents` and `details.max_bytes`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        `rate_limited`: slow down. `Retry-After` says for how long, except when
        a daily allowance is used up: then `details.resets_at` says when it
        renews, and there is no `Retry-After`.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Internal:
      description: >-
        `internal`: something failed on our side. Nothing partial is returned,
        and a request never commits part of itself. Most `internal` errors
        committed nothing. A write can instead fail with a message saying it may
        have been committed, when we could not tell whether its batch landed
        (§7.2.10): it then committed all of it or none of it. Retrying a write
        is safe either way, because writes are idempotent. The message is
        generic and carries a request id, also in `details.request_id`, which
        support uses to find the cause.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        An organization API key. Keys carry a role (`read_write` or
        `read_only`) and may be restricted to a namespace prefix such as
        `acme/*`, or to one namespace such as `acme/prod/tenant_1`. A prefix
        matches on a `/` boundary: `acme/prod/tenant_1*` covers
        `acme/prod/tenant_1` and everything under `acme/prod/tenant_1/`,
        never `acme/prod/tenant_12`.

````