Skip to main content
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 via Authorization: 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:
​
total_input_tokens
number
required
Total input tokens consumed across all agents in this period
​
total_output_tokens
number
required
Total output tokens generated across all agents in this period
​
total_requests
number
required
Total number of API requests across all agents in this period
​
by_agent
array
required
Per-agent breakdown of usage statistics
​
by_agent[].agent_uuid
string
required
Agent UUID
​
by_agent[].agent_name
string
required
Agent name
​
by_agent[].input_tokens
number
required
Input tokens consumed by this agent in the period
​
by_agent[].output_tokens
number
required
Output tokens generated by this agent in the period
​
by_agent[].requests
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

CodeDescription
200Usage summary retrieved successfully
401Unauthorized - invalid or missing authentication