---
title: "Get Agent Metrics"
method: GET
path: "/v1/agents/{id}/metrics"
tags: ["v1"]
---

# Get Agent Metrics

`GET /v1/agents/{id}/metrics`

## Request

- Base URL: `https://api.ellipsis.dev`
- URL: `https://api.ellipsis.dev/v1/agents/{id}/metrics`
- Auth: HTTP bearer

Return an agent's session distribution, trailing spend, and
usage over a window, by id or by name.

`samples` carries one entry per finished session (duration, cost,
tokens) for distributions; `spend_windows` carries what the
agent's sessions cost over the last 1, 7, and 28 days against
its budget for each window; `buckets` splits start to end by
`interval`, chosen from the window's length.

## Path parameters

- `id` string, required

## Query parameters

- `start` string, date-time, required: Inclusive start of the usage window. Naive timestamps use UTC.
- `end` string, date-time, required: Exclusive end of the usage window. Naive timestamps use UTC.

## Headers

- `user-agent` string, nullable

## Response `200`

Successful Response

- AgentMetricsResponse: An agent's session distribution and trailing spend.
  - `buckets` ConfigUsageBucket[], required: Sessions created and usage in each bucket of the window, oldest first, with zeros for buckets without either.
    - `cost` Cost, required: What something cost, in millicents.
      - `charged` integer, required: What Ellipsis charged to credit, in millicents. It is everything except subscription tokens.
      - `cpu` integer, required: CPU spend in millicents.
      - `fee` integer, required: Platform fee in millicents.
      - `llm` LlmCost, required: What LLM tokens cost, in total and by model.
        - `all` LlmCostSplit, required: What LLM tokens cost, in millicents, split by who paid (Ellipsis credit or the user's own subscription).
          - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
          - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
          - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents.
          - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
        - `by_model` ModelLlmCostSplit[], required: Token cost for each model that used tokens.
          - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
          - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
          - `model` string, required: The model that used these tokens.
          - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents.
          - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
      - `memory` integer, required: Memory spend in millicents.
      - `total` integer, required: Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps.
    - `date` string, date-time, required: When the bucket starts, in UTC.
    - `sessions` integer, required: Sessions created in the bucket.
    - `tokens` Tokens, required: Tokens used, in total and by model.
      - `all` TokenCounts, required: Token counts.
        - `cache_creation` integer, required: Tokens written to the prompt cache.
        - `cache_read` integer, required: Tokens read from the prompt cache.
        - `input` integer, required: Input tokens used.
        - `output` integer, required: Output tokens used.
        - `total` integer, required: All tokens used, including prompt cache reads and writes. Token cost is priced on this.
      - `by_model` ModelTokenCounts[], required: Token counts for each model that used tokens.
        - `cache_creation` integer, required: Tokens written to the prompt cache.
        - `cache_read` integer, required: Tokens read from the prompt cache.
        - `input` integer, required: Input tokens used.
        - `model` string, required: The model that used these tokens.
        - `output` integer, required: Output tokens used.
        - `total` integer, required: All tokens used, including prompt cache reads and writes. Token cost is priced on this.
  - `interval` 'hour' | 'day' | 'week', required: The width of one entry in a time series, chosen from the window's length. A window of up to 3 days is split by hour, a window of up to 120 days by day, and a longer window by week. Every entry starts on a UTC boundary of its interval, and a week starts on Monday.
  - `samples` AgentSessionSample[], required: One entry per finished session, unordered.
    - `cost` Cost, required: What something cost, in millicents.
      - `charged` integer, required: What Ellipsis charged to credit, in millicents. It is everything except subscription tokens.
      - `cpu` integer, required: CPU spend in millicents.
      - `fee` integer, required: Platform fee in millicents.
      - `llm` LlmCost, required: What LLM tokens cost, in total and by model.
        - `all` LlmCostSplit, required: What LLM tokens cost, in millicents, split by who paid (Ellipsis credit or the user's own subscription).
          - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
          - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
          - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents.
          - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
        - `by_model` ModelLlmCostSplit[], required: Token cost for each model that used tokens.
          - `claude_subscription` integer, required: Token cost paid by a Claude subscription, at Ellipsis rates, in millicents.
          - `codex_subscription` integer, required: Token cost paid by a Codex subscription, at Ellipsis rates, in millicents.
          - `model` string, required: The model that used these tokens.
          - `platform` integer, required: Token cost charged to Ellipsis credit, in millicents.
          - `total` integer, required: All token cost, in millicents. It is the sum of platform, claude_subscription, and codex_subscription.
      - `memory` integer, required: Memory spend in millicents.
      - `total` integer, required: Everything it cost, whoever paid, in millicents. It is the sum of llm.all.total, cpu, memory, and fee, and it is what the budget caps.
    - `duration_seconds` number, required: Wall-clock seconds from the session's creation to its last update.
    - `tokens` Tokens, required: Tokens used, in total and by model.
      - `all` TokenCounts, required: Token counts.
        - `cache_creation` integer, required: Tokens written to the prompt cache.
        - `cache_read` integer, required: Tokens read from the prompt cache.
        - `input` integer, required: Input tokens used.
        - `output` integer, required: Output tokens used.
        - `total` integer, required: All tokens used, including prompt cache reads and writes. Token cost is priced on this.
      - `by_model` ModelTokenCounts[], required: Token counts for each model that used tokens.
        - `cache_creation` integer, required: Tokens written to the prompt cache.
        - `cache_read` integer, required: Tokens read from the prompt cache.
        - `input` integer, required: Input tokens used.
        - `model` string, required: The model that used these tokens.
        - `output` integer, required: Output tokens used.
        - `total` integer, required: All tokens used, including prompt cache reads and writes. Token cost is priced on this.
  - `spend_windows` ConfigSpendWindow[], required: Trailing spend versus the budget, one entry per window (1, 7, and 28 days).
    - `limit` integer, required: The enforced configuration cap in millicents. It is the configuration's own budget limited to the platform maximum, or the maximum when unset. Account and developer limits also apply.
    - `platform_max` integer, required: The platform ceiling for this window, in millicents.
    - `spent` integer, required: Spend during the window across this configuration's sessions, including subscription tokens, in millicents.
    - `window_days` integer, required: The trailing window in days, which is 1, 7, or 28.

## Other responses

- `401`: The bearer token is missing, invalid, or revoked.
- `403`: The credential may not perform this action, or the account is blocked.
- `404`: No such agent in your account.
- `422`: A time bound is malformed, or start is not earlier than end.

---

[API](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api.md) - [All operations](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/revisions/344b16df9a1a?raw)