# UsageSummary

A range's usage totals, the totals for the same-length range before it, and the split by how runs ended.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `from` | `datetime` | The start of the range, in UTC. |
| `to` | `datetime` | The end of the range, in UTC. |
| `previousFrom` | `datetime` | The start of the comparison range: the same length, ending at `from`. |
| `previousTo` | `datetime` | The end of the comparison range (the same as `from`). |
| `current` | [`UsageTotals`](https://docs.maitento.com/reference/types/usage-totals.md) | The range's totals. |
| `previous` | [`UsageTotals`](https://docs.maitento.com/reference/types/usage-totals.md) | The comparison range's totals. |
| `byOutcome` | [`UsageOutcomeTotals`](https://docs.maitento.com/reference/types/usage-outcome-totals.md)`[]` | The range's usage by outcome: all four outcomes, zero when none. |
| `retentionDays` | `integer` | How many days hourly usage, and each run's usage, is kept. |
| `detailRetentionDays` | `integer` | How many days the usage of each turn and step is kept. |
| `dataFrom` | `datetime \| null` | The start of the tenant's earliest recorded hour, or null when nothing has been recorded. |

## Example

```json
{
  "from": "2026-10-26T12:00:00.0000000Z",
  "to": "2026-10-26T12:00:00.0000000Z",
  "previousFrom": "2026-10-26T12:00:00.0000000Z",
  "previousTo": "2026-10-26T12:00:00.0000000Z",
  "current": {
    "runs": 0,
    "runtimeMs": 0,
    "executionMs": 0,
    "steps": 0,
    "stepRuntimeMs": 0,
    "toolCalls": 0,
    "tokens": {
      "input": 0,
      "output": 0,
      "cacheRead": 0,
      "cacheWrite": 0,
      "reasoning": 0,
      "total": 0
    },
    "webSearches": 0,
    "webPages": 0,
    "webDownloads": 0,
    "imageDescriptions": 0,
    "webCredits": 0,
    "webBytes": 0
  },
  "previous": {
    "runs": 0,
    "runtimeMs": 0,
    "executionMs": 0,
    "steps": 0,
    "stepRuntimeMs": 0,
    "toolCalls": 0,
    "tokens": {
      "input": 0,
      "output": 0,
      "cacheRead": 0,
      "cacheWrite": 0,
      "reasoning": 0,
      "total": 0
    },
    "webSearches": 0,
    "webPages": 0,
    "webDownloads": 0,
    "imageDescriptions": 0,
    "webCredits": 0,
    "webBytes": 0
  },
  "byOutcome": [
    {
      "outcome": "InProgress",
      "totals": {}
    }
  ],
  "retentionDays": 0,
  "detailRetentionDays": 0,
  "dataFrom": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`usage.summary`](https://docs.maitento.com/reference/api/usage.md) (`GET /usage/summary`)