---
title: "Query Usage"
method: GET
path: "/v0/metrics/usage"
tags: ["Metrics"]
---

# Query Usage

`GET /v0/metrics/usage`

Cumulative usage series for the organization. Each point is the running
total of the usage type at that timestamp, not the change within the
bucket. 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.

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