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:

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

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:

  1. Create a GET request to the following endpoint:

    https://{{INSTANCE}}/api/v1/usage/

  2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

  3. (Optional) Append query parameters to filter or adjust the response. For more information, see Query parameters.

  4. 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#

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