# LLM usage — tool reference

Generated from the OpenAPI document (`https://maison-labs.com/api/v1/openapi.json`). Field types are JSON Schema types; GET/DELETE inputs travel as path or query, other methods as a JSON body.

## `get_llm_usage_summary` — LLM usage summary

Aggregated LLM token and cost totals for a date window, grouped by day, model, purpose or client. Window must not exceed 31 days. Costs are list-price estimates.

- REST: `GET https://maison-labs.com/api/v1/llmusage/summary`
- MCP tool / A2A skill: `get_llm_usage_summary`
- Needs: llm-usage READ (global)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `from` | query | string | yes | Start date YYYY-MM-DD (inclusive) |
| `to` | query | string | yes | End date YYYY-MM-DD (inclusive) |
| `groupBy` | query | enum: day \| model \| purpose \| client | no | Dimension to group results by; default "day" |
| `clientId` | query | string | no | Limit to a specific client; format uuid |
| `purpose` | query | enum: guest_chat \| admin_agent \| agent_evaluate \| agent_route \| agent_draft \| agent_split \| chat_feedback \| conversation_topic \| knowledge_gap \| analytics_report \| diagnostic \| translate \| follow_ups \| email_judge \| classify \| addon_intent \| embedding \| other | no | Limit to a specific purpose |

## `list_llm_usage` — List LLM usage records

Individual LLM call records for a date window (newest first, up to 100 per page). Window must not exceed 31 days. Filter by clientId or purpose.

- REST: `GET https://maison-labs.com/api/v1/llmusage`
- MCP tool / A2A skill: `list_llm_usage`
- Needs: llm-usage READ (global)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `from` | query | string | yes | Start date YYYY-MM-DD (inclusive) |
| `to` | query | string | yes | End date YYYY-MM-DD (inclusive) |
| `clientId` | query | string | no | Limit to a specific client; format uuid |
| `purpose` | query | enum: guest_chat \| admin_agent \| agent_evaluate \| agent_route \| agent_draft \| agent_split \| chat_feedback \| conversation_topic \| knowledge_gap \| analytics_report \| diagnostic \| translate \| follow_ups \| email_judge \| classify \| addon_intent \| embedding \| other | no | Limit to a specific purpose |
| `limit` | query | integer | no | Page size (1–100); default 20 |
| `after` | query | string | no | Opaque cursor from the previous page's `nextCursor`; omit for the first page |