> ## 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 Usage

> Return combined LLM and Droyd sandbox usage for an evaluation.

Use this route to inspect the combined usage record for one evaluation. It
returns LLM and Droyd sandbox summaries with redacted event detail, making it
useful for comparing runs without exposing credentials or model input/output.

Auth: Droyd API key or signed-in user bearer token. Alias:
`GET /api/v1/evaluations/{id}/usage`. The evaluation must be owned by the
authenticated account; inaccessible IDs return `404`. The response has
`evaluation_id`, `llm`, `compute`, `llm_usage_events`, and
`compute_usage`. Treat totals as the currently recorded usage for the run,
not as a balance or a payment instruction. The `compute` summary includes the
calculated customer cost plus CPU, memory, and GPU cost splits;
its resource-time fields use CPU core-seconds, memory GiB-seconds, and GPU
seconds. These values are provisional, and a record can remain unavailable while its
cost is still being calculated. `500` uses a route-specific usage-load error
code when its dependencies cannot be read.


## OpenAPI

````yaml api-key.openapi.json GET /v1/evaluations/{id}/usage
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}/usage:
    get:
      tags:
        - Usage
      summary: Return combined LLM and Droyd sandbox usage for one evaluation.
      operationId: getEvaluationUsage
      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.

````