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

Full input fields for every tool: 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.

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

// 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": {} } }

// 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.