# Analytics and reports — 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_ai_visibility_report` — Fetch an AI visibility analytics report

Retrieve a completed AI-visibility analytics report: with `format: "html"` (default) the run metadata and the full HTML (up to 2 MiB); with `format: "xlsx"` the metadata and a download `url` for the spreadsheet, valid for 5 minutes (`expiresAt`). 404 when the report does not exist. Use get_chatlog_report for chat-log reports.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/report/aivisibility/{analyticsId}`
- MCP tool / A2A skill: `get_ai_visibility_report`
- Needs: ai-visibility-analytics READ (client)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `analyticsId` | path | string | yes | Analytics session id from list_ai_visibility_reports; format uuid |
| `format` | query | enum: html \| xlsx | no | html: the report inline (≤ 2 MiB). xlsx: a short-lived download URL for the spreadsheet version; default "html" |

## `get_chatlog_report` — Fetch a chat-log analytics report

Retrieve a completed chat-log analytics report: with `format: "html"` (default) the run metadata and the full HTML (up to 2 MiB); with `format: "xlsx"` the metadata and a download `url` for the spreadsheet, valid for 5 minutes (`expiresAt`). 404 when the report does not exist or has not yet been generated. Use get_ai_visibility_report for AI-visibility reports.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/report/chatlogs/{analyticsId}`
- MCP tool / A2A skill: `get_chatlog_report`
- Needs: chat-log-analytics READ (client)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `analyticsId` | path | string | yes | Analytics session id from list_chatlog_reports; format uuid |
| `format` | query | enum: html \| xlsx | no | html: the report inline (≤ 2 MiB). xlsx: a short-lived download URL for the spreadsheet version; default "html" |

## `get_conversation_analytics` — Conversation analytics for one hotel

The Analytics page figures for one hotel over [from, to] (ISO 8601 date-times, at most 400 UTC days): conversations and conversations answered without handoff, knowledge gaps opened / resolved / open, each compared with the equal-length previous window (`previous` is null before the hotel's first indexed conversation), the daily conversation count per channel, the median days to resolve a gap, and the top 10 open unanswered questions — `unanswered` is null unless the caller may also read conversations (chat-logs). Booking links and leads are reported as not tracked. Use get_portfolio_analytics for every hotel at once.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/analytics/conversations`
- MCP tool / A2A skill: `get_conversation_analytics`
- Needs: chat-log-analytics READ (client); client plan must include `chat-log-analytics`
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `from` | query | string | yes | Window start (inclusive), ISO 8601 with offset; format date-time |
| `to` | query | string | yes | Window end (inclusive), ISO 8601 with offset; format date-time |

## `get_dashboard_stats` — Client dashboard stats

System-wide counts (active clients, users) and a recent activity feed for one hotel. The activityLimit parameter controls how many activity events are returned (1–50, default 10). Use get_portfolio_overview for cross-hotel analytics.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/dashboard`
- MCP tool / A2A skill: `get_dashboard_stats`
- Needs: dashboard READ (client)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `activityLimit` | query | integer | no | Number of recent activity items to return (1–50); default 10 |

## `get_portfolio_analytics` — Portfolio analytics

The Portfolio page figures over [from, to] (ISO 8601 date-times, at most 400 UTC days) across every enabled hotel the caller may read with analytics in its plan: summed conversations, answered without handoff and open gaps against the previous window, a per-property table, the daily conversations per channel, the top 10 unanswered questions across properties (only for hotels whose conversations the caller may read), and `needsYou` — integration or website-sync errors and open knowledge gaps, most urgent first. Use get_conversation_analytics for one hotel, get_portfolio_overview for health and trends.

- REST: `GET https://maison-labs.com/api/v1/portfolio/analytics`
- MCP tool / A2A skill: `get_portfolio_analytics`
- Needs: clients READ (any), chat-log-analytics READ (any)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `from` | query | string | yes | Window start (inclusive), ISO 8601 with offset; format date-time |
| `to` | query | string | yes | Window end (inclusive), ISO 8601 with offset; format date-time |

## `get_portfolio_overview` — Portfolio overview

Health metrics and conversation trends across every hotel in the caller's portfolio over a date window (YYYY-MM-DD). Optionally scoped to a group (multi-property parent) by groupId. 404 when the principal has no accessible clients. Use get_dashboard_stats for a single hotel.

- REST: `GET https://maison-labs.com/api/v1/portfolio/overview`
- MCP tool / A2A skill: `get_portfolio_overview`
- Needs: clients READ (any)
- 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) |
| `groupId` | query | string | no | Limit to children of this multi-property group client; format uuid |

## `list_ai_visibility_reports` — List AI visibility analytics report history

Page through past AI-visibility analytics runs for a hotel ordered newest first. Use get_ai_visibility_report to fetch the HTML of a specific run. Use list_chatlog_reports for chat-log runs.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/reports/aivisibility`
- MCP tool / A2A skill: `list_ai_visibility_reports`
- Needs: ai-visibility-analytics READ (client)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `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 |
| `status` | query | enum: QUEUED \| IN_PROGRESS \| ERROR \| DONE | no | Filter by run status: QUEUED \| IN_PROGRESS \| ERROR \| DONE |

## `list_chatlog_reports` — List chat-log analytics report history

Page through past chat-log analytics runs for a hotel ordered newest first. Use get_chatlog_report to fetch the HTML of a specific run. Use list_ai_visibility_reports for AI-visibility runs.

- REST: `GET https://maison-labs.com/api/v1/client/{clientId}/reports/chatlogs`
- MCP tool / A2A skill: `list_chatlog_reports`
- Needs: chat-log-analytics READ (client)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `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 |
| `status` | query | enum: QUEUED \| IN_PROGRESS \| ERROR \| DONE | no | Filter by run status: QUEUED \| IN_PROGRESS \| ERROR \| DONE |

## `list_report_runs` — List analytics report runs

Page through analytics report runs (one row per run and hotel), newest first, across every hotel the caller may read — chat-log and AI-visibility runs alike, narrowed to the report types the caller holds. Filter by `type`, `status` and `clientId`. Each row says whether a report exists (`hasReport`); fetch it with get_chatlog_report / get_ai_visibility_report. Returns `items`, `nextCursor` and `total`.

- REST: `GET https://maison-labs.com/api/v1/reports`
- MCP tool / A2A skill: `list_report_runs`
- Needs: chat-log-analytics READ (any)
- Read-only.

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | query | string | no | Only this hotel's runs; format uuid |
| `type` | query | enum: CHAT_LOGS \| AI_VISIBILITY | no | Report type |
| `status` | query | enum: QUEUED \| IN_PROGRESS \| ERROR \| DONE | no | Filter by run status: QUEUED \| IN_PROGRESS \| ERROR \| DONE |
| `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 |

## `rerun_ai_visibility_report` — Rerun a failed AI visibility analytics report

Reset errored clients in an existing AI-visibility analytics session back to QUEUED and requeue the SQS pipeline. Returns scheduled and failed counts. 404 when the session does not exist. Use rerun_chatlog_report for chat-log sessions.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/report/aivisibility/{analyticsId}/rerun`
- MCP tool / A2A skill: `rerun_ai_visibility_report`
- Needs: ai-visibility-analytics EXECUTE (client)

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `analyticsId` | path | string | yes | Analytics session id to rerun; format uuid |

## `rerun_chatlog_report` — Rerun a failed chat-log analytics report

Reset errored clients in an existing chat-log analytics session back to QUEUED and requeue the pipeline. Returns scheduled and (for AI_VISIBILITY sessions, which this tool rejects via type mismatch) failed counts. 404 when the session does not exist. Use rerun_ai_visibility_report for AI-visibility sessions.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/report/chatlogs/{analyticsId}/rerun`
- MCP tool / A2A skill: `rerun_chatlog_report`
- Needs: chat-log-analytics EXECUTE (client)

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `analyticsId` | path | string | yes | Analytics session id to rerun; format uuid |

## `run_ai_visibility_report` — Run an AI visibility analytics report

Trigger an asynchronous AI-visibility report for one hotel. Returns sessionId and status. Use get_ai_visibility_report to retrieve the HTML report once the pipeline completes. Use run_chatlog_report for conversation-quality analytics.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/report/aivisibility`
- MCP tool / A2A skill: `run_ai_visibility_report`
- Needs: ai-visibility-analytics EXECUTE (client); client plan must include `ai-visibility-analytics`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `recipients` | body | object | no | Optional email delivery of the finished report |

## `run_chatlog_report` — Run a chat-log analytics report

Trigger an asynchronous chat-log analytics report for one hotel. The pipeline processes the logs and optionally emails the HTML report to the specified recipients. Returns the analyticsId (use get_chatlog_report to retrieve the HTML when ready). Use run_ai_visibility_report for AI visibility analytics.

- REST: `POST https://maison-labs.com/api/v1/client/{clientId}/report/chatlogs`
- MCP tool / A2A skill: `run_chatlog_report`
- Needs: chat-log-analytics EXECUTE (client); client plan must include `chat-log-analytics`

Inputs:

| Field | Where | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `clientId` | path | string | yes | Client (hotel) id; format uuid |
| `startDate` | body | string | no | Report window start as ISO 8601 date; default: 30 days ago |
| `endDate` | body | string | no | Report window end as ISO 8601 date; default: today |
| `recipients` | body | object | no | Email delivery; omit to skip email and only store the report |