Viewing workspace usage metrics in Management API

On this page

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

See GET /api/v1/usage/ in the API reference.

Prerequisites

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

Use a Connect API key with Usage: Read-only (usage:read). Without this permission, Management API returns HTTP 403. You cannot change the permissions of a key, so to add one, create a new key. For more information, see Creating a Connect API key in Adverity.

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.

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 value Bearer {{KEY}}.
(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: Bearer {{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}}'

Query parameters

Scroll horizontally to see the full table.

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:

Scroll horizontally to see the full table.

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`.