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

# Usage

> Aggregated cost and usage breakdown for your workspace.

## Get Usage Summary

```
GET /v1/usage/summary
```

Returns aggregated cost breakdown for today, last 7 days, and last 30 days, plus breakdowns by model and by user.

**Auth**: JWT or API Key

### Response `200`

```json theme={null}
{
  "today": {
    "total_usd": 12.50,
    "total_tokens": 250000,
    "run_count": 45
  },
  "last_7_days": {
    "total_usd": 85.20,
    "total_tokens": 1700000,
    "run_count": 312
  },
  "last_30_days": {
    "total_usd": 340.00,
    "total_tokens": 6800000,
    "run_count": 1250
  },
  "by_model": [
    {
      "model": "gpt-4o",
      "total_usd": 280.00,
      "prompt_tokens": 4500000,
      "completion_tokens": 900000
    },
    {
      "model": "gpt-4o-mini",
      "total_usd": 60.00,
      "prompt_tokens": 1200000,
      "completion_tokens": 200000
    }
  ],
  "by_user": [
    {
      "user_id": "alice",
      "total_usd": 150.00,
      "run_count": 520
    },
    {
      "user_id": "bob",
      "total_usd": 190.00,
      "run_count": 730
    }
  ],
  "monthly_run_count": 1250,
  "monthly_run_limit": 50000
}
```

### Response Fields

| Field               | Type              | Description                                         |
| ------------------- | ----------------- | --------------------------------------------------- |
| `today`             | `CostBreakdown`   | Aggregated costs for today                          |
| `last_7_days`       | `CostBreakdown`   | Aggregated costs for the last 7 days                |
| `last_30_days`      | `CostBreakdown`   | Aggregated costs for the last 30 days               |
| `by_model`          | `ModelCost[]`     | Cost breakdown by model                             |
| `by_user`           | `UserCost[]`      | Cost breakdown by SDK user                          |
| `monthly_run_count` | `integer`         | Total runs this calendar month                      |
| `monthly_run_limit` | `integer \| null` | Monthly run limit from plan tier (null = unlimited) |

### CostBreakdown

| Field          | Type      | Description           |
| -------------- | --------- | --------------------- |
| `total_usd`    | `number`  | Total cost in USD     |
| `total_tokens` | `integer` | Total tokens consumed |
| `run_count`    | `integer` | Number of runs        |

### ModelCost

| Field               | Type      | Description               |
| ------------------- | --------- | ------------------------- |
| `model`             | `string`  | Model identifier          |
| `total_usd`         | `number`  | Total cost for this model |
| `prompt_tokens`     | `integer` | Total prompt tokens       |
| `completion_tokens` | `integer` | Total completion tokens   |

### UserCost

| Field       | Type      | Description                 |
| ----------- | --------- | --------------------------- |
| `user_id`   | `string`  | SDK user identifier         |
| `total_usd` | `number`  | Total cost for this user    |
| `run_count` | `integer` | Number of runs by this user |