Get Usage Summary
curl --request GET \
--url https://api.app.shinzo.ai/v1/spotlight/analytics/usage-summary \
--header 'Authorization: Bearer <token>'{
"total_input_tokens": 123,
"total_output_tokens": 123,
"total_requests": 123,
"by_agent": [
{}
],
"by_agent[].agent_uuid": "<string>",
"by_agent[].agent_name": "<string>",
"by_agent[].input_tokens": 123,
"by_agent[].output_tokens": 123,
"by_agent[].requests": 123
}Get Usage Summary
Get a compact token usage summary for today, this week, and this month broken down by agent.
GET
/
v1
/
spotlight
/
analytics
/
usage-summary
Get Usage Summary
curl --request GET \
--url https://api.app.shinzo.ai/v1/spotlight/analytics/usage-summary \
--header 'Authorization: Bearer <token>'{
"total_input_tokens": 123,
"total_output_tokens": 123,
"total_requests": 123,
"by_agent": [
{}
],
"by_agent[].agent_uuid": "<string>",
"by_agent[].agent_name": "<string>",
"by_agent[].input_tokens": 123,
"by_agent[].output_tokens": 123,
"by_agent[].requests": 123
}Authentication
Requires JWT token or Platform API key viaAuthorization: Bearer <token> header.
Example Request
curl https://api.app.shinzo.ai/v1/spotlight/analytics/usage-summary \
-H "Authorization: Bearer <token>"
Example Response
{
"today": {
"total_input_tokens": 12450,
"total_output_tokens": 8920,
"total_requests": 15,
"by_agent": [
{
"agent_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"agent_name": "My Assistant",
"input_tokens": 8200,
"output_tokens": 6100,
"requests": 10
},
{
"agent_uuid": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
"agent_name": "Code Helper",
"input_tokens": 4250,
"output_tokens": 2820,
"requests": 5
}
]
},
"this_week": {
"total_input_tokens": 85300,
"total_output_tokens": 62400,
"total_requests": 98,
"by_agent": [
{
"agent_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"agent_name": "My Assistant",
"input_tokens": 58000,
"output_tokens": 42000,
"requests": 65
},
{
"agent_uuid": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
"agent_name": "Code Helper",
"input_tokens": 27300,
"output_tokens": 20400,
"requests": 33
}
]
},
"this_month": {
"total_input_tokens": 342000,
"total_output_tokens": 256000,
"total_requests": 420,
"by_agent": [
{
"agent_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"agent_name": "My Assistant",
"input_tokens": 230000,
"output_tokens": 170000,
"requests": 280
},
{
"agent_uuid": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
"agent_name": "Code Helper",
"input_tokens": 112000,
"output_tokens": 86000,
"requests": 140
}
]
}
}
Response Fields
The response contains three time period summaries:today, this_week, and this_month. Each period has the same structure:
number
required
Total input tokens consumed across all agents in this period
number
required
Total output tokens generated across all agents in this period
number
required
Total number of API requests across all agents in this period
array
required
Per-agent breakdown of usage statistics
string
required
Agent UUID
string
required
Agent name
number
required
Input tokens consumed by this agent in the period
number
required
Output tokens generated by this agent in the period
number
required
Number of API requests made by this agent in the period
This endpoint is much faster than listing all sessions and summing manually. Use it to quickly answer “how many tokens did I burn today?” without scanning through full session history.
Time Periods
- today: Current calendar day (UTC)
- this_week: Current calendar week (Monday-Sunday, UTC)
- this_month: Current calendar month (UTC)
Status Codes
| Code | Description |
|---|---|
200 | Usage summary retrieved successfully |
401 | Unauthorized - invalid or missing authentication |