Maison — Analytics and reports

Measure and report: the Analytics page figures for one hotel and the Portfolio page figures across every hotel the caller may read (conversations, answered without handoff, knowledge gaps, daily channels, top unanswered questions, needs-you items), a portfolio overview, per-hotel dashboard statistics, and chat-log and AI-visibility reports (run, list runs across hotels, read as HTML or download as a spreadsheet, rerun). Use when asked how a hotel or portfolio is performing, to produce a periodic report, or to email a report to recipients.

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

• Portfolio health over a period — get_portfolio_overview with from/to.
• One hotel's numbers — get_dashboard_stats.
• Produce and deliver a report — run_chatlog_report or run_ai_visibility_report with recipients.
• One hotel's conversation figures against the previous period — get_conversation_analytics with ISO from/to.
• Every hotel at once, with what needs attention — get_portfolio_analytics.
• Report runs across hotels, failed ones first — list_report_runs with status: "ERROR".

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

Run and read a chat-log report

1. run_chatlog_report with optional startDate/endDate and recipients.to[] (202, returns analyticsId).
2. Poll list_chatlog_reports (or list_report_runs) until the run's status is DONE (ERROR = failed; QUEUED/IN_PROGRESS = still running).
3. get_chatlog_report with the analyticsId for the HTML, or format: "xlsx" for a 5-minute download URL of the spreadsheet; rerun_chatlog_report to regenerate.

Tips

• Reports are per type with their own grants: chat-log tools need chat-log-analytics, AI-visibility tools need ai-visibility-analytics.
• Report and overview dates are ISO YYYY-MM-DD; the portfolio overview is inclusive of both ends.
• get_conversation_analytics / get_portfolio_analytics take ISO 8601 date-times (with offset), at most 400 UTC days; previous is null — not zero — when the earlier window predates the hotel's indexed history.
• The unanswered-question lists need conversation read access (chat-logs); without it unanswered is null.

Pitfalls

• A 409 from run_*_report means a run is already in flight for that hotel — poll the history instead of retrying.
• get_*_report returns HTML inline and refuses documents over 2 MiB — use format: "xlsx" for a download link instead; the link expires after 5 minutes.
• Run status values are exactly QUEUED, IN_PROGRESS, ERROR, DONE.
• In get_portfolio_overview, a null conversation count means that period's chat history is not available for that hotel; it is not zero. conversationCoverage says how many hotels report.

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/client/<clientId>/report/aivisibility/<analyticsId>" -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_ai_visibility_report", "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_ai_visibility_report", "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.