---
name: "maison-usage"
description: "Answer spend questions about LLM calls across the platform: total tokens and estimated costs by day, model, purpose or client, and individual call records for a date window. Costs are list-price estimates. Use get_llm_usage_summary to chart trends (line or bar block); use list_llm_usage to inspect individual records. Windows must not exceed 31 days. Tools: get_llm_usage_summary, list_llm_usage."
license: "Proprietary. Use with a Maison API key under the Maison terms of service."
metadata:
  author: "maison-labs"
  version: "1.0.0"
  category: "usage"
  api-base: "https://maison-labs.com"
  openapi: "https://maison-labs.com/api/v1/openapi.json"
  docs: "https://docs.maison-labs.com/skills/maison-usage/"
---

# Maison — LLM usage

Answer spend questions about LLM calls across the platform: total tokens and estimated costs by day, model, purpose or client, and individual call records for a date window. Costs are list-price estimates. Use get_llm_usage_summary to chart trends (line or bar block); use list_llm_usage to inspect individual records. Windows must not exceed 31 days.

Part of the Maison public API. Read the `maison-public-api` skill first for authentication, discovery and transport details (`https://docs.maison-labs.com/skills/maison-public-api/SKILL.md`).

## When to use

- Summarise token spend by model or purpose over the last week — `get_llm_usage_summary` with `groupBy: 'model'`.
- Chart daily cost trends — `get_llm_usage_summary` with `groupBy: 'day'`.
- Inspect individual LLM calls for a session or run — `list_llm_usage` with `clientId` or `purpose`.

## Before you start

1. Send `x-api-key: <key>` on every call; the key only reaches `/api/v1`.
2. `GET /api/v1/tools` (or MCP `tools/list`) returns the tools THIS key may run — if a tool below is missing there, you lack a grant; do not retry it.
3. Client-scoped tools take `clientId` (a hotel id). `whoami` lists the ids you can act on.

## Tools

| Tool | What it does | REST | Needs |
| --- | --- | --- | --- |
| `get_llm_usage_summary` | Aggregated LLM token and cost totals for a date window, grouped by day, model, purpose or client. | `GET /api/v1/llmusage/summary` | llm-usage READ (global); read-only |
| `list_llm_usage` | Individual LLM call records for a date window (newest first, up to 100 per page). | `GET /api/v1/llmusage` | llm-usage READ (global); read-only |

Full input fields for every tool: [references/tools.md](references/tools.md).

## Recommended workflows

### Chart spend over a period

1. `get_llm_usage_summary` with `from`/`to` (YYYY-MM-DD) and `groupBy: 'day'`.
2. Use the returned `buckets[]` to render a line or bar block — each bucket has `key` (date), `inputTokens`, `outputTokens`, `totalTokens` and `costUsd`.
3. Narrow by `clientId` or `purpose` to isolate a hotel or call type.

## Tips

- Costs (`costUsd`) are list-price estimates computed at record time; actual invoiced amounts may differ.
- `groupBy: 'client'` shows spend per hotel; `groupBy: 'purpose'` breaks down by call type (guest_chat, translate, etc.).

## Pitfalls

- Windows exceeding 31 days are rejected with a 400 error — split into smaller ranges.
- Both tools require a global `llm-usage` READ grant (Maison staff only).

## Calling conventions

Same tool, three transports — pick whichever your runtime already speaks. Always send `x-api-key`.

```bash
# REST
curl -X GET "https://maison-labs.com/api/v1/llmusage/summary" -H "x-api-key: $MAISON_API_KEY"
```

```json
// MCP (https://maison-labs.com/mcp, Streamable HTTP): tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_llm_usage_summary", "arguments": {} } }
```

```json
// A2A (https://maison-labs.com/a2a): tasks/send with a data part
{ "jsonrpc": "2.0", "id": 1, "method": "tasks/send", "params": { "message": { "role": "user", "parts": [{ "type": "data", "data": { "tool": "get_llm_usage_summary", "input": {} } }] } } }
```

Errors are the same everywhere: `401` no/invalid key; `403 forbidden` with `details.missing` (the grants you lack — fall back to the composite's parts or stop); `403 not_entitled` (the hotel's plan lacks the feature); `404`, `409`, `413 too_large`, `503`. Inputs that fail validation return `400 invalid_input` with the Zod issues — fix and retry once.