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

# Get Run Evaluation

> Returns just the assertion roll-up. Equivalent to `runs/:id` but trimmed to the `evaluation` field — useful for CI checks where you don't need the transcript. Always returns 200 (404 only when the run id is unknown); `score`, `pass_fail`, and `evaluation` are null until the run reaches a terminal status. Gate CI on `GET /agent-eval/runs/{id}` reaching a terminal `status` AND `queue_status === "done"` rather than on this endpoint's HTTP code.


Returns just the assertion roll-up — equivalent to `GET /agent-eval/runs/:id` but trimmed to the `evaluation` field. Useful for CI checks where you only care about the score.

The scoring fields aren't final until the worker finishes both the conversation AND the assertion pass. Poll the parent `GET /agent-eval/runs/:id` until `queue_status === "done"`, **then** call this endpoint. If you hit this endpoint while `queue_status` is still `pending` or `claimed`, `score` / `pass_fail` / `results` will be null.

## Response shape

```json theme={null}
{
  "score": 87.5,
  "pass_fail": true,
  "results": [
    {
      "assertion": { "type": "must_say", "pattern": "Tuesday at 3pm", "weight": 1 },
      "passed": true,
      "weight": 1,
      "reason": "matched at turn 7"
    },
    {
      "assertion": { "type": "must_call_tool", "tool_name": "bookAppointment", "weight": 2 },
      "passed": true,
      "weight": 2,
      "reason": "fired at turn 8"
    }
  ]
}
```


## OpenAPI

````yaml GET /agent-eval/runs/{id}/evaluation
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /agent-eval/runs/{id}/evaluation:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags:
        - Agent Eval
      summary: Get run evaluation
      description: >
        Returns just the assertion roll-up. Equivalent to `runs/:id` but trimmed
        to the `evaluation` field — useful for CI checks where you don't need
        the transcript. Always returns 200 (404 only when the run id is
        unknown); `score`, `pass_fail`, and `evaluation` are null until the run
        reaches a terminal status. Gate CI on `GET /agent-eval/runs/{id}`
        reaching a terminal `status` AND `queue_status === "done"` rather than
        on this endpoint's HTTP code.
      operationId: getRunEvaluation
      responses:
        '200':
          description: Evaluation result. Fields are null until the run is terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evaluation'
        '404':
          description: Run not found
components:
  schemas:
    Evaluation:
      type: object
      description: >-
        Roll-up of assertion results that's also stored on
        `eval_runs.evaluation`.
      required:
        - score
        - pass_fail
        - results
      properties:
        score:
          type: number
          minimum: 0
          maximum: 100
          description: Weighted percentage of assertions that passed.
        pass_fail:
          type: boolean
          description: True iff `score >= case.pass_threshold`.
        results:
          type: array
          items:
            $ref: '#/components/schemas/AssertionResult'
    AssertionResult:
      type: object
      description: One assertion's outcome after the run completed.
      required:
        - assertion
        - passed
        - weight
      properties:
        assertion:
          $ref: '#/components/schemas/Assertion'
        passed:
          type: boolean
        weight:
          type: number
        reason:
          type: string
          nullable: true
          description: >-
            Short human-readable explanation. For LLM judges this is the judge's
            verdict.
    Assertion:
      type: object
      description: >
        A single success criterion attached to an eval case. Discriminated by
        `kind`. Each assertion has a `weight` (defaults to 1.0) used in the
        weighted score calculation: `score = sum(weight * passed?1:0) /
        sum(weight) * 100`. Cases pass when `score >= pass_threshold`.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - must_say
            - must_not_say
            - must_call_tool
            - must_reach_node
            - custom_llm_judge
          description: >
            Assertion kind. Each kind reads a different combination of the
            sibling fields below.
        weight:
          type: number
          default: 1
          minimum: 0
          description: Relative weight in the case score.
        description:
          type: string
          nullable: true
          description: >-
            Optional human-readable note shown in the dashboard alongside this
            assertion.
        pattern:
          type: string
          nullable: true
          description: >
            For `must_say` / `must_not_say`: a regex evaluated against the full
            agent transcript (case-insensitive). Plain substrings work too —
            they're valid regex. For literal punctuation, escape with
            backslashes (e.g. `goodbye\\?`).
        tool_name:
          type: string
          nullable: true
          description: >-
            `must_call_tool` only: name of a tool the agent must invoke at least
            once during the run.
        args_match:
          type: object
          additionalProperties: true
          nullable: true
          description: >
            `must_call_tool` only: optional shape the tool's arguments must
            match. Each key must equal the value. The sentinel `"$present"`
            checks the key exists with a non-null value.
        node_id:
          type: string
          nullable: true
          description: >-
            `must_reach_node` only: flow node id the run must enter. Only
            meaningful for flow agents — silently fails for prompt-mode agents.
        rubric:
          type: string
          nullable: true
          description: >-
            `custom_llm_judge` only: natural-language rubric the judge LLM
            scores the run against. (Engine stub in v1 — returns `passed=false,
            reason='not_implemented'`; full LLM-as-judge ships in v1.1.)
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````