Appearance

List Usage ​

Endpoint ​

http
GET /unified/usage-metering/usage
Integrations supported
  • Claude
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog

Query parameters ​

Refer Specifying query parameters in Truto APIs

integrated_account_id
string · uuid
REQUIRED · 

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

Example: 62f44730-dd91-461e-bd6a-aedd9e0ad79d
truto_response_format
string

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.

All possible enum values:
  • unified
  • raw
  • normalized
  • stream
  • debug
Example: unified
truto_key_by
string

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_limit
boolean

Ignores the limit query parameter.

truto_ignore_remote_data
boolean

Excludes the remote_data attribute from the response.

truto_exclude_fields
array

Array of fields to exclude from the response.

Example: truto_exclude_fields[]=id&truto_exclude_fields[]=name
remote_query
object

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
date
string · date
Integration specific notes
  • ClaudeDate for which to retrieve records, in YYYY-MM-DD format. If omitted, the date from 3 days ago is used by default.
  • OpenAI CodexDay to retrieve OpenAI usage for, in YYYY-MM-DD format. Defaults to yesterday.
Supported in
  • Claude
  • OpenAI Codex
start_date
string · date-time

The start date for the usage data.

Integration specific notes
  • OpenAI CodexAlias for `date`. Accepts YYYY-MM-DD or RFC3339 date-time; only the day portion is used.
  • ConfluentIf not specified, it defaults to the start of the current month.
  • CursorInclusive range start (ISO 8601). Mapped to Cursor startDate epoch ms.
  • DatadogIf not specified, it defaults to the start of the current month. Only supports maximum resolution of a month.
Supported in
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog
user_id
string

Filter usage to a specific OpenAI user ID.

Supported in
  • OpenAI Codex
end_date
string · date-time

The end date for the usage data.

Integration specific notes
  • ConfluentIf not specified, it defaults to the end of the current month or the end of the month specified in the start date.
  • CursorInclusive range end (ISO 8601). Mapped to Cursor endDate epoch ms.
  • DatadogIf 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.
Supported in
  • Confluent
  • Cursor
  • Datadog

Response Body ​

result
object[]

List of Usage

id
string
REQUIRED · 

Unique identifier for the usage.

Supported in
  • Claude
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog
product
object

The product associated with the usage.

Supported in
  • Claude
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog
id
string
REQUIRED · 

Unique identifier for the product.

name
string

Name of the product.

metric_name
string

Name of the metric being charged for

Supported in
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog
resources
object[]
Supported in
  • OpenAI Codex
  • Confluent
id
string

Unique identifier for the resource.

name
string

Name of the resource.

workspace
object

The resource is present in this workspace.

id
string

Unique identifier for the workspace.

name
string

Name of the workspace.

organization
object

The organization associated with the usage.

Supported in
  • OpenAI Codex
  • Datadog
id
string
REQUIRED · 

Unique identifier for the organization.

name
string

Name of the organization.

user
object

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

Supported in
  • Claude
  • OpenAI Codex
  • Cursor
id
string

Unique identifier for the user in the source application.

email
string

Primary email of the user.

name
string

Display name of the user.

model
object

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

Supported in
  • OpenAI Codex
  • Cursor
id
string

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

provider
string

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

charges
object[]

The amounts charged for the usage.

Supported in
  • Confluent
  • Datadog
amount
number

The amount charged for the usage.

currency
string

The currency in which the charge is made.

type
string

The type of charge.

All possible enum values:
  • total
  • net
  • on_demand
  • committed
  • included
  • usage_based
  • discount
  • tax
  • credit
  • platform_fee
usage
object

The usage data for the product.

Supported in
  • Claude
  • OpenAI Codex
  • Confluent
  • Cursor
quantity
number

Generic quantity (e.g. Confluent).

unit
string

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

requests
object
total
number
chat
number
agent
number
composer
number
cmdk
number

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

tab_shown
number
tab_accepted
number
api_key
number
included
number
usage_based
number
bugbot
number
sessions
object
distinct
number
dispatch_turns
number

Cowork / background dispatch turns.

conversations
object
distinct
number
message_count
number
thinking_message_count
number
shared_viewed_count
number
turn_count
number
thread_count
number
code
object
lines_added
number
lines_removed
number
lines_accepted_added
number
lines_accepted_removed
number
applies
number
accepts
number
rejects
number
commits
number
pull_requests
number
tool_actions
object

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

file_extensions
object
apply_most_used
string
tab_most_used
string
tokens
object
input
number
output
number
cache_read
number
cache_write
number
cache_write_ephemeral_5m
number
cache_write_ephemeral_1h
number
total
number
tools
object
web_search_count
number
connectors_used_count
number
distinct_connectors_used_count
number
skills_used_count
number
distinct_skills_used_count
number
action_count
number
activity
object
is_active
boolean
max_mode
boolean
client_version
string
start_date
string · date-time

The start date for the usage data.

Supported in
  • Claude
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog
end_date
string · date-time

The end date for the usage data.

Supported in
  • Claude
  • OpenAI Codex
  • Confluent
  • Cursor
  • Datadog
created_at
string · date-time

Date and time when the usage data metric was created.

updated_at
string · date-time

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

surface
string

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.

remote_data
object

Raw data returned from the remote API call.

next_cursor
string

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.

debug
object

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.

requestUrl
string
requestOptions
object
data
responseHeaders
object
nextCursor
string
isLooping
boolean
isEmptyResult
boolean
resultCount
number