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

# Get Evaluation

> Return one evaluation with related links.

Use this route to poll evaluation status and discover related result endpoints.

While an evaluation is active, the response may include a `progress` snapshot:

```json theme={null}
{
  "ok": true,
  "evaluation": {
    "id": "b870ff4a-9d50-4da2-bf15-24221efc0600",
    "status": "running"
  },
  "progress": {
    "phase": "running_tasks",
    "completed": 12,
    "total": 30,
    "remaining": 18,
    "failed": 1,
    "updated_at": "2026-07-17T12:00:00Z",
    "stale": false
  },
  "links": {}
}
```

`progress` is `null` before an attempt starts, between retry attempts, or when
an older evaluation has no progress snapshot. Poll this route about every 15
seconds. The snapshot is refreshed by the evaluation worker about every 30
seconds, so consecutive responses may contain the same counts.

`failed` counts tasks that ended with an execution error or timeout. It is not
a partial benchmark score and should not be used to predict the final result.
Final scores and result rows become available through the result endpoints
after the evaluation finishes.

Auth: Droyd API key or signed-in user bearer token. Alias:
`GET /api/v1/evaluations/{id}`. Status enum: `queued`, `starting`, `running`,
`ingesting`, `succeeded`, `failed`, `cancelled`, `expired`, `dead_letter`.
Terminal statuses are `succeeded`, `failed`, `cancelled`, `expired`, and
`dead_letter`. Progress phases are `preparing`, `running_tasks`, `scoring`,
`finalizing`, and `complete`. `stale: true` means the non-terminal run has not
reported fresh progress for over 90 seconds; continue polling rather than
declaring failure. Progress is aggregate-only and never contains hidden data,
prompts, outputs, or partial scores.


## OpenAPI

````yaml api-key.openapi.json GET /v1/evaluations/{id}
openapi: 3.1.0
info:
  title: Droyd API-key Automation API
  version: 1.0.0
  description: >-
    The production API contract for Droyd API-key automations. It contains only
    operations that accept a Droyd API key. `/v1` is canonical; `/api/v1` is a
    compatibility alias.
servers: []
security:
  - droydApiKeyBearer: []
  - droydApiKeyHeader: []
tags:
  - name: Identity
    description: Account-scoped automation identity and onboarding state.
  - name: Workflows
    description: Caller-owned workflows and research nodes.
  - name: Competitions
    description: Competition readiness, submissions, and race entries.
  - name: Experiments
    description: Experiments, artifacts, agent versions, and evaluations.
  - name: Usage
    description: Caller-owned evaluation usage.
  - name: Billing
    description: Caller-owned prepaid credit balances and funding.
paths:
  /v1/evaluations/{id}:
    get:
      tags:
        - Experiments
      summary: Poll evaluation status, progress, and related links.
      operationId: getEvaluation
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    Success:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Account state or route policy prevents the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The resource is missing or not owned by the API-key account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServerError:
      description: >-
        The request could not be completed. Retry only when the operation's
        idempotency contract permits it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - ok
      properties:
        ok:
          const: true
      additionalProperties: true
    ErrorEnvelope:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    droydApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: Droyd API key
      description: A Droyd API key in the Authorization Bearer slot.
    droydApiKeyHeader:
      type: apiKey
      in: header
      name: x-droyd-api-key
      description: A Droyd API key when Authorization is absent.

````