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

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:

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

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

Get Usage Summary

Authentication

Example Request

Example Response

Response Fields

Time Periods

Status Codes

​Authentication

​Example Request

​Example Response

​Response Fields

​Time Periods

​Status Codes

Authentication

Example Request

Example Response

Response Fields

Time Periods

Status Codes