Viewing workspace usage metrics in Management API

Viewing workspace usage metrics in Management API#

This guide explains how to retrieve finalized row-usage metrics for billing and cost-allocation purposes using the Management API.

Prerequisites#

Before you complete the procedures in this guide, perform all of the following actions:

Obtain a Management API key with the usage:read scope. For more information, see Authorizing to Management API.

Retrieving usage metrics#

The GET /api/v1/usage/ endpoint returns finalized row-usage metrics grouped by date, workspace, and datastream. Results are scoped to the API key’s workspace and all workspaces beneath it.

Note

Usage data is finalized daily. The current day is always excluded — date_to is capped to yesterday regardless of the value you provide.

To retrieve usage metrics, follow these steps:

Create a GET request to the following endpoint:
```
https://{{INSTANCE}}/api/v1/usage/
```
In the HTTP request header, include the parameter Authorization with one of the following values:
- Token {{KEY}} if you use a key generated with user credentials in Management API.
- Bearer {{KEY}} if you use a key generated in the Adverity user interface.
(Optional) Append query parameters to filter or adjust the response. For more information, see Query parameters.
Send the request.

As a result, you obtain a paginated list of row-usage metrics.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl -G 'https://{{INSTANCE}}/api/v1/usage/' \
--header 'Authorization: Token {{KEY}}' \
--data-urlencode 'granularity=monthly' \
--data-urlencode 'date_from=2026-05-01' \
--data-urlencode 'date_to=2026-06-18' \
--data-urlencode 'workspace_id={{WORKSPACE_UUID}}'

Note

If you have generated your API key in the Adverity user interface, replace Token with Bearer in the Authorization header.

Query parameters#

Parameter	Description
`granularity`	Reporting granularity. Accepted values: `daily` (default), `monthly`.
`date_from`	Start date in `YYYY-MM-DD` format (inclusive). Defaults to the first day of the current month if omitted.
`date_to`	End date in `YYYY-MM-DD` format (inclusive). Defaults to yesterday. Always capped to yesterday — the current day is excluded until daily aggregation completes.
`workspace_id`	UUID of a workspace to filter by. Repeatable to include multiple workspaces. Results are limited to workspaces within the API key’s subtree — unknown or out-of-scope UUIDs are silently ignored.
`datastream_id`	UUID of a datastream to filter by. Repeatable to include multiple datastreams. Unknown or out-of-scope UUIDs are silently ignored.
`page`	Page number for pagination. Default: `1`.
`page_size`	Number of results per page. Default: `50`. Maximum: `100`.

Response fields#

The response contains an items array and a count field with the total number of matching records. Each item in items represents one date × workspace × datastream bucket:

Field	Description
`date`	The start of the reporting period. For `monthly` granularity, the first day of the month.
`workspace_id`	UUID of the workspace.
`workspace_name`	Name of the workspace. Returned inline so no follow-up lookup is needed.
`datastream_id`	UUID of the datastream. `null` when the row is not attributable to a specific datastream.
`unique_rows`	Number of unique rows processed. Never `null`.
`total_rows`	Total number of rows processed, including duplicates. Never `null`.