--- title: "Get workspace usage" method: POST path: "/v2/workspace.getUsage" tags: ["workspace"] --- # Get workspace usage `POST /v2/workspace.getUsage` ## Request - Base URL: `https://api.unkey.com` - URL: `https://api.unkey.com/v2/workspace.getUsage` - Auth: HTTP bearer Get the usage of your workspace for one calendar month (UTC): billable API operations, compute usage per environment, and active keys per app. Use this to track usage during the month or to look back at a past month. The response has no prices. Your invoice is the source of truth. Compute usage can be up to 15 minutes late, and it can change for up to 7 days. Send `{}` for the current month to date, or `{"period": {"year": 2026, "month": 9}}` for a full past month. The month must start within the last 90 days. **Required Permissions** Your root key must have this permission: - `unkey:v1::usage#read` ## Request body - V2WorkspaceGetUsageRequestBody - `period` V2WorkspaceGetUsageRequestPeriod: The calendar month (UTC) to read. Omit it for the current month to date. A past month returns the full month. It cannot be in the future, and it must start within the last 90 days, because compute usage is kept for 90 days. - `year` integer, required: The year, for example 2026. - `month` integer, required: The month, from 1 (January) to 12 (December). ## Response `200` The workspace usage for the requested month. - V2WorkspaceGetUsageResponseBody - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team. - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance. - `data` V2WorkspaceGetUsageResponseData, required - `period` V2WorkspaceGetUsagePeriod, required: The time window the usage covers. - `start` integer, required: Unix timestamp in milliseconds of the first day of the month, 00:00 UTC. - `end` integer, required: Unix timestamp in milliseconds of the end of the period, exclusive. For the current month it is the time of the request. For a past month it is the start of the next month. - `totals` V2WorkspaceGetUsageTotals, required: Workspace totals in the period. `compute` is the sum of `breakdowns.byEnvironment[].compute`. `gateway.activeKeys` is the sum of `breakdowns.byApp[].gateway.activeKeys`. - `api` V2WorkspaceGetUsageApi, required: Billable operations through the Unkey API in the period. Key verifications through the Unkey gateway are not counted here. The gateway bills by active keys, see `gateway`. - `verifications` integer, required: Billable key verifications. - `ratelimits` integer, required: Billable rate limit operations. - `compute` V2WorkspaceGetUsageCompute, required: Compute usage in the period. - `cpuSeconds` number, double, required: CPU time used, in seconds. - `memoryGiBHours` number, double, required: Memory used over time, in GiB-hours. - `storageGiBHours` number, double, required: Ephemeral disk reserved over time, in GiB-hours. - `egressGiB` number, double, required: Public network egress, in GiB. - `gateway` V2WorkspaceGetUsageGateway, required: Unkey gateway usage in the period. - `activeKeys` integer, required: Distinct keys verified through the Unkey gateway. A key verified through several apps counts once, for the app that verified it most. - `breakdowns` V2WorkspaceGetUsageBreakdowns, required: The totals split by environment and by app. - `byEnvironment` V2WorkspaceGetUsageByEnvironmentRow[], required: One row per environment with compute usage in the period, most `compute.cpuSeconds` first, then by project id and environment id. Empty when nothing ran. - `project` V2WorkspaceGetUsageResource, required: A project or app. `name` is omitted when the resource was deleted. - `id` string, required: The resource id. - `name` string: The resource name. - `app` V2WorkspaceGetUsageResource: A project or app. `name` is omitted when the resource was deleted. - `id` string, required: The resource id. - `name` string: The resource name. - `environment` V2WorkspaceGetUsageEnvironmentResource, required: An environment. `slug` is omitted when the environment was deleted. - `id` string, required: The environment id. - `slug` string: The environment slug. - `compute` V2WorkspaceGetUsageCompute, required: Compute usage in the period. - `cpuSeconds` number, double, required: CPU time used, in seconds. - `memoryGiBHours` number, double, required: Memory used over time, in GiB-hours. - `storageGiBHours` number, double, required: Ephemeral disk reserved over time, in GiB-hours. - `egressGiB` number, double, required: Public network egress, in GiB. - `byApp` V2WorkspaceGetUsageByAppRow[], required: One row per app whose gateway verified keys in the period, and one row without `app` for keys that have no app id. Most `gateway.activeKeys` first, then by app id. Empty when no keys were verified. - `project` V2WorkspaceGetUsageResource: A project or app. `name` is omitted when the resource was deleted. - `id` string, required: The resource id. - `name` string: The resource name. - `app` V2WorkspaceGetUsageResource: A project or app. `name` is omitted when the resource was deleted. - `id` string, required: The resource id. - `name` string: The resource name. - `gateway` V2WorkspaceGetUsageGateway, required: Unkey gateway usage in the period. - `activeKeys` integer, required: Distinct keys verified through the Unkey gateway. A key verified through several apps counts once, for the app that verified it most. ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - Insufficient permissions (requires `unkey:v1::usage#read`) - `429`: Too Many Requests - `500`: Internal server error ## Changes - **2026-10-07** `d4e613f318dc`: 1 info - endpoint added [Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/workspace.getUsage/post.md) --- [API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)