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

> Return hourly or daily evaluation-resource and LLM-inference usage for the caller.

Returns the evaluation runtime and LLM usage shown in the Droyd Usage view. The
default period is the 30 days ending when the request is made.

Use `competition_id` to filter evaluation and inference usage, or `model` to
filter inference usage. The response includes the competitions and models used
in the selected period for building filter controls. Set `bucket=hour` for an
hourly series or `bucket=day` for a daily series; `day` is the default.

Evaluation usage records CPU, memory, and GPU device time consumed in Droyd
sandboxes, plus calculated Droyd sandbox runtime cost. GPU time and cost are
aggregated across chip types. `unavailable_runs` identifies sandbox runs whose
cost could not be calculated completely.

Auth: Droyd API key or signed-in user bearer token. Alias: `GET /api/v1/usage`.
Optional query parameters are `bucket` (`hour` or `day`, default `day`),
`competition_id` (UUID), `model` (1-200 characters), and `from`/`to` (ISO 8601
timestamps with timezone offsets). Duplicate or unknown query parameters return
`400 invalid_request`; the range must be positive and at most 366 days. The
account is derived from authentication and cannot be supplied by the client.
The response exposes usage telemetry and calculated Droyd sandbox runtime cost,
including pre-markup and customer component fields for CPU, memory, and GPU. It
is not an account balance or credit-management operation. Raw traces,
credentials, and provider request payloads are not returned.


## OpenAPI

````yaml api-key.openapi.json GET /v1/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/usage:
    get:
      tags:
        - Usage
      summary: Return caller-owned evaluation runtime and LLM usage.
      operationId: getUsage
      parameters:
        - name: bucket
          in: query
          schema:
            type: string
            enum:
              - hour
              - day
            default: day
        - name: competition_id
          in: query
          schema:
            type: string
            format: uuid
        - name: model
          in: query
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Success:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    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'
    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.

````