Overview

GET /api/v1/agent/usage/tokens

Overview

The Token Usage endpoint provides aggregated token consumption statistics for the authenticated project. This endpoint can be used to monitor AI usage, track consumption trends, estimate costs, and build internal reporting dashboards.

The returned values represent the total number of input and output tokens processed by the Statement Agent API for your project.

For security and privacy reasons, this endpoint only returns aggregate usage metrics. It does not expose individual requests, prompts, responses, model configuration details, API keys, routing decisions, or raw usage records.

Request

No request body is required.

Example Request

curl -X GET https://api.statement.com/api/v1/agent/usage/tokens \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response

Example Response

{
  "input_tokens": 1200,
  "output_tokens": 450,
  "total_tokens": 1650
}

Response Fields

Usage Calculation

The total_tokens value is calculated as:

total_tokens = input_tokens + output_tokens

Using the example response:

1200 + 450 = 1650

Common Use Cases

• Monitor project-wide AI consumption
• Track usage growth over time
• Estimate infrastructure or AI-related costs
• Build internal analytics dashboards
• Implement usage reporting for customers or teams
• Audit overall platform utilization

Data Privacy

This endpoint only returns aggregated usage statistics.

The following information is never exposed through this endpoint:

• User prompts
• Agent responses
• Conversation history
• API keys
• Connected service credentials
• Model provider information
• Internal routing decisions
• Raw usage documents or logs

Notes

• Usage statistics are scoped to the authenticated project.
• Values represent aggregate totals and are not grouped by conversation, user, model, or service.
• Token counts may increase as new requests are processed through the Agent API.
• This endpoint is intended for reporting and monitoring purposes and should not be used to retrieve request-level activity.