---
title: "Query Usage"
method: GET
path: "/v0/pods/{pod_id}/metrics/usage"
tags: ["PodsMetrics"]
---

# Query Usage

`GET /v0/pods/{pod_id}/metrics/usage`

Cumulative usage series for the pod. Each point is the running total of
the usage type at that timestamp, not the change within the bucket.
Pod-scoped queries carry every usage type except `pod_count`; requested
types that don't apply to the scope are ignored. Defaults to the last
24 hours; `start` must be within the last 90 days, and a future `end`
is clamped to now. The range divided by `period` must not exceed 1000
buckets.

## Path parameters

- `pod_id` string, required — ID of pod.

## Query parameters

- `usage_types` UsageType[] — List of usage metric types to query. Omit to query every type valid for the scope.
- `start` string, date-time — Start timestamp for the query.
- `end` string, date-time — End timestamp for the query.
- `period` integer — Size of each time bucket as a whole number of seconds, between 1 and 86400.
- `limit` integer — Limit on number of buckets to return.
- `descending` boolean — Sort in descending order.

## Response `200`

- QueryUsageResponse — Cumulative usage series grouped by usage type.

## Other responses

- `400`

---

[API](https://skmtc.net/agentmail-to/apis/api.md) · [All operations](https://skmtc.net/agentmail-to/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentmail-to/api/revisions/394ddcdd9c29/schema)