> ## Documentation Index
> Fetch the complete documentation index at: https://metacognition-fdc534de-master.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Monthly usage summary

> Read monthly token rollups in UTC.

Returns a calendar-month usage rollup in UTC. If you omit `month`, the endpoint returns the current month.

## Headers

```http theme={null}
Authorization: Bearer <access_token>
```

## Query

<ParamField query="month" type="string">
  `"YYYY-MM"`. Omit for the current month.
</ParamField>

## Response — `200`

<ResponseField name="period" type="string">
  Always `"month"`.
</ResponseField>

<ResponseField name="start" type="string">
  First moment of the month in UTC.
</ResponseField>

<ResponseField name="end" type="string">
  First moment of the next month in UTC.
</ResponseField>

<ResponseField name="tokens_in" type="integer">
  Total ingress tokens for the month.
</ResponseField>

<ResponseField name="tokens_out" type="integer">
  Total egress tokens for the month.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  # Current month
  curl -H "Authorization: Bearer $JWT" \
    https://api.getmetacognition.com/usage/summary

  # Specific month
  curl -H "Authorization: Bearer $JWT" \
    "https://api.getmetacognition.com/usage/summary?month=2026-04"
  ```

  ```python Python theme={null}
  import httpx

  resp = httpx.get(
      "https://api.getmetacognition.com/usage/summary",
      headers={"Authorization": f"Bearer {jwt}"},
      params={"month": "2026-04"},
  )
  print(resp.json())
  ```
</CodeGroup>

```json Response theme={null}
{
  "period": "month",
  "start": "2026-05-01T00:00:00+00:00",
  "end":   "2026-06-01T00:00:00+00:00",
  "tokens_in": 12,
  "tokens_out": 27
}
```

## Charting tip

Pull six months in parallel for a rolling chart:

```python theme={null}
import asyncio, httpx
from datetime import date

months = [(date(2026, m, 1)).strftime("%Y-%m") for m in range(1, 7)]

async def fetch(client, m):
    r = await client.get("/usage/summary", params={"month": m})
    return m, r.json()

async def main():
    async with httpx.AsyncClient(
        base_url="https://api.getmetacognition.com",
        headers={"Authorization": f"Bearer {jwt}"},
    ) as c:
        return dict(await asyncio.gather(*(fetch(c, m) for m in months)))

print(asyncio.run(main()))
```