> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Usage Summary

> Get a compact token usage summary for today, this week, and this month broken down by agent.

## Authentication

Requires JWT token or Platform API key via `Authorization: Bearer <token>` header.

## Example Request

```bash theme={null}
curl https://api.app.shinzo.ai/v1/spotlight/analytics/usage-summary \
  -H "Authorization: Bearer <token>"
```

## Example Response

```json theme={null}
{
  "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:

<ResponseField name="total_input_tokens" type="number" required>
  Total input tokens consumed across all agents in this period
</ResponseField>

<ResponseField name="total_output_tokens" type="number" required>
  Total output tokens generated across all agents in this period
</ResponseField>

<ResponseField name="total_requests" type="number" required>
  Total number of API requests across all agents in this period
</ResponseField>

<ResponseField name="by_agent" type="array" required>
  Per-agent breakdown of usage statistics
</ResponseField>

<ResponseField name="by_agent[].agent_uuid" type="string" required>
  Agent UUID
</ResponseField>

<ResponseField name="by_agent[].agent_name" type="string" required>
  Agent name
</ResponseField>

<ResponseField name="by_agent[].input_tokens" type="number" required>
  Input tokens consumed by this agent in the period
</ResponseField>

<ResponseField name="by_agent[].output_tokens" type="number" required>
  Output tokens generated by this agent in the period
</ResponseField>

<ResponseField name="by_agent[].requests" type="number" required>
  Number of API requests made by this agent in the period
</ResponseField>

<Tip>
  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.
</Tip>

## 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 |