Skip to content
GET /unified/usage-metering/usage

Query Parameters

Refer Specifying query parameters in Truto APIs

report_typestring

Usage view to retrieve. Defaults to activity unless a date range is supplied.

Possible values:
activityconnector_usagecostproject_usageskill_usagesummaryusageuser_costuser_usage
1 supported
Claude
supported
start_datestring · date-time

The start date for the usage data.

5 supported5 notes
Claude
supported

Inclusive usage period start. Accepts YYYY-MM-DD or RFC3339 date-time. For daily activity-style views, the date portion is used.

OpenAI Codex
supported

Alias for date. Accepts YYYY-MM-DD or RFC3339 date-time; only the day portion is used.

Confluent
supported

If not specified, it defaults to the start of the current month.

Cursor
supported

Inclusive range start (ISO 8601). Mapped to Cursor startDate epoch ms.

Datadog
supported

If not specified, it defaults to the start of the current month. Only supports maximum resolution of a month.

end_datestring · date-time

The end date for the usage data.

4 supported4 notes
Claude
supported

Exclusive usage period end. Accepts YYYY-MM-DD or RFC3339 date-time. Defaults to a recent completed period when omitted.

Confluent
supported

If not specified, it defaults to the end of the current month or the end of the month specified in the start date.

Cursor
supported

Inclusive range end (ISO 8601). Mapped to Cursor endDate epoch ms.

Datadog
supported

If not specified, it defaults to the end of the current month or the end of the month specified in the start date. Only supports maximum resolution of a month.

product_idsstring[]

Filter usage to specific unified product IDs or source product identifiers.

1 supported
Claude
supported
user_idsstring[]

Filter usage to specific source user IDs.

1 supported
Claude
supported
model_idsstring[]

Filter usage to specific AI model IDs.

1 supported
Claude
supported
surfacesstring[]

Filter usage to specific product surfaces such as chat, api, cli, composer, or code.

1 supported
Claude
supported
group_bystring[]

Generic dimensions to group by, such as product, surface, model, user, charge_type, or token_type when supported by the provider.

1 supported
Claude
supported
granularitystring

Time bucket size for bucketed usage or cost reports when supported by the provider.

Possible values:
dayhourminute
1 supported
Claude
supported
sort_bystring

Metric or dimension to sort by when supported by the provider.

1 supported
Claude
supported
sort_orderstring

Sort direction.

Possible values:
ascdesc
1 supported
Claude
supported
include_deleted_usersboolean

Whether deleted users should be included when the provider supports that distinction.

1 supported
Claude
supported
limitnumber

Maximum number of records to return.

2 supported
Claude
supported
Cursor
supported
cursorstring

Pagination cursor from the previous response.

1 supported
Claude
supported
datestring

Day to retrieve OpenAI usage for, in YYYY-MM-DD format. Defaults to yesterday.

1 supported
OpenAI Codex
supported
user_idstring

Filter usage to a specific OpenAI user ID.

1 supported
OpenAI Codex
supported
api_key_idstring

Filter usage to a specific OpenAI API key ID.

1 supported
OpenAI Codex
supported
pagenumber
1 supported
Cursor
supported
page_sizenumber
1 supported
Cursor
supported
Show Truto-specific parameters
integrated_account_idstring · uuid
required·

The ID of the integrated account to use for the request.

Example: 62f44730-dd91-461e-bd6a-aedd9e0ad79d
truto_response_formatstring

The format of the response.

  • unified returns the response with unified mappings applied.
  • raw returns the unprocessed, raw response from the remote API.
  • normalized applies the unified mappings and returns the data in a normalized format.
  • stream returns the response as a stream, which is ideal for transmitting large datasets, files, or binary data. Using streaming mode helps to efficiently handle large payloads or real-time data flows without requiring the entire data to be buffered in memory.
  • debug returns the final unified result alongside raw remote fetch information. The response is an envelope containing result (identical to unified mode output) and debug (with requestUrl, requestOptions, data, responseHeaders, and for list operations: nextCursor, isLooping, isEmptyResult, resultCount). debug is null for static responses or when truto_skip_api_call=true.

Defaults to unified.

Example: unified
Possible values:
unifiedrawnormalizedstreamdebug
truto_key_bystring

By default the result attribute is an array of objects. This parameter allows you to specify a field in each result objects to use as key, which transforms the result array into an object with the array items keyed by the field. This is useful for when you want to use the result as a lookup table.

Example: id
truto_ignore_limitboolean

Ignores the limit query parameter.

truto_ignore_remote_databoolean

Excludes the remote_data attribute from the response.

truto_exclude_fieldsstring[]

Array of fields to exclude from the response.

Example: truto_exclude_fields[]=id&truto_exclude_fields[]=name
remote_queryRecord<string, any>

Query parameters to pass to the underlying API without any transformations. Refer this guide to see how to structure the query parameters.

Example: remote_query[foo]=bar

Response Body

debugobject

Present only when truto_response_format=debug. Contains raw fetch details: requestUrl, requestOptions, data, responseHeaders, nextCursor, isLooping, isEmptyResult, resultCount. null for static responses or when truto_skip_api_call=true.

data
isEmptyResultboolean
isLoopingboolean
nextCursorstring
requestOptionsRecord<string, any>
requestUrlstring
responseHeadersRecord<string, any>
resultCountnumber
next_cursorstring

The cursor to use for the next page of results. Pass this value as next_cursor in the query parameter in the next request to get the next page of results.

resultobject[]

List of Usage

idstring
required·

Unique identifier for the usage.

5 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
Cursor
supported
Datadog
supported
chargesobject[]

The amounts charged for the usage.

3 supported
Claude
supported
Confluent
supported
Datadog
supported
3 properties
amountnumber

The amount charged for the usage.

currencystring

The currency in which the charge is made.

typestring

The type of charge.

Possible values:
totalneton_demandcommittedincludedusage_baseddiscounttaxcreditplatform_fee
created_atstring · date-time

Date and time when the usage data metric was created.

1 supported
Claude
supported
end_datestring · date-time

The end date for the usage data.

5 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
Cursor
supported
Datadog
supported
metric_namestring

Name of the metric being charged for

5 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
Cursor
supported
Datadog
supported
modelobject

AI model for the row when applicable. Omit for non-AI vendors.

3 supported
Claude
supported
OpenAI Codex
supported
Cursor
supported
2 properties
idstring

Model identifier (e.g. claude-sonnet-4-6, gpt-5).

providerstring

Provider hosting the model (e.g. anthropic, openai, cursor).

organizationobject

The organization associated with the usage.

2 supported
OpenAI Codex
supported
Datadog
supported
2 properties
idstring
required·

Unique identifier for the organization.

namestring

Name of the organization.

productobject

The product associated with the usage.

5 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
Cursor
supported
Datadog
supported
2 properties
idstring
required·

Unique identifier for the product.

namestring

Name of the product.

remote_dataRecord<string, any>

Raw data returned from the remote API call.

resourcesobject[]
3 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
3 properties
idstring

Unique identifier for the resource.

namestring

Name of the resource.

workspaceobject

The resource is present in this workspace.

2 properties
idstring

Unique identifier for the workspace.

namestring

Name of the workspace.

start_datestring · date-time

The start date for the usage data.

5 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
Cursor
supported
Datadog
supported
surfacestring

Specific product surface for this row when the source exposes a single surface, such as chat, claude_code, cowork, office_agent, composer, or api. Omit when the row is aggregate and no per-surface split exists.

1 supported
Claude
supported
updated_atstring · date-time

Date and time when the usage data metric was last updated.

usageobject

The usage data for the product.

4 supported
Claude
supported
OpenAI Codex
supported
Confluent
supported
Cursor
supported
9 properties
activityobject
3 properties
client_versionstring
is_activeboolean
max_modeboolean
codeobject
11 properties
acceptsnumber
appliesnumber
commitsnumber
file_extensionsobject
2 properties
apply_most_usedstring
tab_most_usedstring
lines_accepted_addednumber
lines_accepted_removednumber
lines_addednumber
lines_removednumber
pull_requestsnumber
rejectsnumber
tool_actionsRecord<string, any>

Per-tool accept/reject counts (e.g. Claude Code).

conversationsobject
6 properties
distinctnumber
message_countnumber
shared_viewed_countnumber
thinking_message_countnumber
thread_countnumber
turn_countnumber
quantitynumber

Generic quantity (e.g. Confluent).

requestsobject
11 properties
agentnumber
api_keynumber
bugbotnumber
chatnumber
cmdknumber

Inline edit (e.g. Cursor Cmd+K).

composernumber
includednumber
tab_acceptednumber
tab_shownnumber
totalnumber
usage_basednumber
sessionsobject
2 properties
dispatch_turnsnumber

Cowork / background dispatch turns.

distinctnumber
tokensobject
7 properties
cache_readnumber
cache_writenumber
cache_write_ephemeral_1hnumber
cache_write_ephemeral_5mnumber
inputnumber
outputnumber
totalnumber
toolsobject
6 properties
action_countnumber
connectors_used_countnumber
distinct_connectors_used_countnumber
distinct_skills_used_countnumber
skills_used_countnumber
web_search_countnumber
unitstring

Unit for quantity (e.g. GB, request, hour).

userobject

User attributed to the usage row when the vendor exposes a user pivot. Omit for org-level or aggregated rows.

3 supported
Claude
supported
OpenAI Codex
supported
Cursor
supported
3 properties
emailstring

Primary email of the user.

idstring

Unique identifier for the user in the source application.

namestring

Display name of the user.

truto unified usage-metering usage \
  -a '<integrated_account_id>' \
  -o json
import Truto from '@truto/truto-ts-sdk';

const truto = new Truto({
  token: '<your_api_token>',
});

const result = await truto.unifiedApi.list(
  'usage-metering',
  'usage',
  { integrated_account_id: '<integrated_account_id>' }
);

console.log(result);
import asyncio
from truto_python_sdk import TrutoApi

truto_api = TrutoApi(token="<your_api_token>")

async def main():
    async for item in truto_api.unified_api.list(
        "usage-metering",
        "usage",
        {"integrated_account_id": "<integrated_account_id>"}
    ):
        print(item)

asyncio.run(main())
curl -X GET 'https://api.truto.one/unified/usage-metering/usage?integrated_account_id=<integrated_account_id>' \
  -H 'Authorization: Bearer <your_api_token>' \
  -H 'Content-Type: application/json'
const integratedAccountId = '<integrated_account_id>';

const response = await fetch(`https://api.truto.one/unified/usage-metering/usage?integrated_account_id=${integratedAccountId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token>',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
import requests

url = "https://api.truto.one/unified/usage-metering/usage"
headers = {
    "Authorization": "Bearer <your_api_token>",
    "Content-Type": "application/json",
}
params = {
    "integrated_account_id": "<integrated_account_id>"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())