# Get account information Source: https://docs.otterly.ai/api-reference/accounts/get-account-information https://data.otterly.ai/v1/openapi.json get /v1/accounts/info Returns the authenticated team's subscription plan, end date, and current period usage/limits for prompts, GEO audits, public API requests, and MCP tool calls. # Create a content check Source: https://docs.otterly.ai/api-reference/audits/create-a-content-check https://data.otterly.ai/v1/openapi.json post /v1/audits/geo/content-checks # Create a crawlability check Source: https://docs.otterly.ai/api-reference/audits/create-a-crawlability-check https://data.otterly.ai/v1/openapi.json post /v1/audits/geo/crawlability-checks # Create a query fan-out Source: https://docs.otterly.ai/api-reference/audits/create-a-query-fan-out https://data.otterly.ai/v1/openapi.json post /v1/audits/query-fan-outs # Get a content check Source: https://docs.otterly.ai/api-reference/audits/get-a-content-check https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/content-checks/{checkId} # Get a crawlability check Source: https://docs.otterly.ai/api-reference/audits/get-a-crawlability-check https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/crawlability-checks/{checkId} # Get a query fan-out Source: https://docs.otterly.ai/api-reference/audits/get-a-query-fan-out https://data.otterly.ai/v1/openapi.json get /v1/audits/query-fan-outs/{fanOutId} # List content checks Source: https://docs.otterly.ai/api-reference/audits/list-content-checks https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/content-checks # List crawlability checks Source: https://docs.otterly.ai/api-reference/audits/list-crawlability-checks https://data.otterly.ai/v1/openapi.json get /v1/audits/geo/crawlability-checks # List query fan-outs Source: https://docs.otterly.ai/api-reference/audits/list-query-fan-outs https://data.otterly.ai/v1/openapi.json get /v1/audits/query-fan-outs # Add a note to a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/add-a-note-to-a-brand-report https://data.otterly.ai/v1/openapi.json post /v1/reports/brand/{reportId}/annotations Adds a note on a day of the brand report, authored by the API key user. Only notes can be created: recommendation markers are added from the recommendations page in the app, and a `type` other than `note` or a `recommendationId` is a 400. Annotations may not show in the dashboard until annotations are enabled there for your account; they are stored and returned by the API either way. # Add prompts to a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/add-prompts-to-a-brand-report https://data.otterly.ai/v1/openapi.json post /v1/reports/brand/{reportId}/prompts Adds prompts that already exist in the report workspace to the brand report, exactly like ticking the report in the UI. It does not create prompts — use `POST /v1/workspaces/{id}/prompts` for that. Prompt IDs already assigned to the report are returned in `alreadyAssigned` and left unchanged; unknown prompt IDs are rejected with a 400 naming them. The report is recalculated for the added prompts asynchronously, so their data appears with a delay. A prompt that was previously removed from this report is reprocessed for the most recent 7 days of citation history only. # Create a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/create-a-brand-report https://data.otterly.ai/v1/openapi.json post /v1/reports/brand Creates a brand report in a workspace, the same as creating it in the UI. The prompts must already exist in that workspace — create them with `POST /v1/workspaces/{id}/prompts` — and the report tracks their countries. Domains are normalized (protocol, `www.` and path stripped). Detect the brand either by `brand` and `brandVariations`, or by `brandRegex` together with `reportTitle`. Competitors can come straight from `POST /v1/competitors/suggestions`. Data for the report is collected asynchronously. Sending the same request again within 2 minutes returns the report the first request created instead of a second one; if that report is still being set up, the response is a 409 carrying its ID. # Delete a brand report annotation Source: https://docs.otterly.ai/api-reference/brand-reports/delete-a-brand-report-annotation https://data.otterly.ai/v1/openapi.json delete /v1/reports/brand/{reportId}/annotations/{annotationId} Removes a note or a recommendation marker from the brand report. Removing a recommendation marker does not change the recommendation itself. An annotation that is not on this report, or was already deleted, is a 404. # Edit a brand report note Source: https://docs.otterly.ai/api-reference/brand-reports/edit-a-brand-report-note https://data.otterly.ai/v1/openapi.json patch /v1/reports/brand/{reportId}/annotations/{annotationId} Changes the `text` and/or `date` of a note; send at least one. Read-only fields (`id`, `brandReportId`, `type`, `recommendationId`, `createdBy`, `createdDate`, `updatedDate`) are ignored, so an item from the list can be sent back as is. Only notes can be edited: a recommendation annotation is a 403 (it can still be listed and deleted). An annotation that is not on this report is a 404. # Get a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/get-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId} # Get AI agent traffic overview for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/get-ai-agent-traffic-overview-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/agent-analytics/stats Overview of AI crawler and agent traffic across the brand report's own domains: total visits, distinct pages visited, the busiest engine, per-engine totals, and a daily trend with each engine's share. Check `availability` before rendering — `not_connected` means no logs connector is set up and the metrics are `null`, not zero. # Get citation history for a cited URL Source: https://docs.otterly.ai/api-reference/brand-reports/get-citation-history-for-a-cited-url https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations/history # Get citation statistics for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/get-citation-statistics-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations/stats # Get prompt details from a brand report. Source: https://docs.otterly.ai/api-reference/brand-reports/get-prompt-details-from-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/prompts/{promptId} # Get statistics for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/get-statistics-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/stats # List AI agents that visited a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/list-ai-agents-that-visited-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/agent-analytics/agents Per-agent breakdown of AI crawler traffic, busiest agent first. `category` says what the agent is doing — fetching a page for a user, building a search index, or collecting training data — which is usually more actionable than the engine alone. # List AI responses for a prompt in a brand report. Source: https://docs.otterly.ai/api-reference/brand-reports/list-ai-responses-for-a-prompt-in-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/prompts/{promptId}/ai-responses # List brand report annotations Source: https://docs.otterly.ai/api-reference/brand-reports/list-brand-report-annotations https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/annotations Returns every annotation on the brand report, notes and recommendation markers, most recently created first. Send `startDate` and `endDate` together to return only annotations dated in that range (inclusive), ordered by annotation date, latest first; a lone bound or a `startDate` after `endDate` is a 400. Annotations may not show in the dashboard until annotations are enabled there for your account; they are stored and returned by the API either way. # List brand reports Source: https://docs.otterly.ai/api-reference/brand-reports/list-brand-reports https://data.otterly.ai/v1/openapi.json get /v1/reports/brand # List citations for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/list-citations-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations # List pages visited by AI agents for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/list-pages-visited-by-ai-agents-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/agent-analytics/pages Per-URL breakdown of AI agent traffic, busiest page first. Pages are segmented per domain: the same path on the report's main domain and on a domain variation are two separate items. URLs are normalized at ingest — query strings are stripped and the path is domain-relative. # List prompts for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/list-prompts-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/prompts # List prompts for a cited URL Source: https://docs.otterly.ai/api-reference/brand-reports/list-prompts-for-a-cited-url https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/citations/prompts # List recommendations for a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/list-recommendations-for-a-brand-report https://data.otterly.ai/v1/openapi.json get /v1/reports/brand/{reportId}/recommendations # Remove prompts from a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/remove-prompts-from-a-brand-report https://data.otterly.ai/v1/openapi.json delete /v1/reports/brand/{reportId}/prompts Unassigns prompts from the brand report and recalculates it without them (asynchronously). The prompt IDs travel in a JSON request body, which some HTTP clients drop on DELETE — send it explicitly. The prompts themselves are not deleted and stay in the workspace — use `DELETE /v1/workspaces/{id}/prompts/{promptId}` for that. Prompt IDs that are not assigned to the report are returned in `notAssigned` and left unchanged; unknown prompt IDs are rejected with a 400 naming them. This discards the citation data collected for those prompts in this report: re-adding one later reprocesses only the most recent 7 days of its citation history, so a remove-then-re-add round trip is not reversible. # Update a brand report Source: https://docs.otterly.ai/api-reference/brand-reports/update-a-brand-report https://data.otterly.ai/v1/openapi.json patch /v1/reports/brand/{reportId} Changes only the fields you send; an array field you send replaces the stored one whole. A field sent with its stored value is left unchanged and is not re-validated, so a GET body can be sent back as is: its read-only fields (`workspaceId`, `id`, `countries`, `tags`, `createdDate`, `updatedDate`, `countryPromptsTotal`) are ignored, and the workspace of a report cannot be changed. Send `brandRegex: null` to clear the detection regex. Changing detection fields (brand, variations, domains, wildcard, regex or competitors) recalculates the report history for every past day, exactly like an edit in the UI, so updated numbers appear with a delay. Changing `promptIds` adds and removes prompts the same way as the prompt assignment endpoints. # Suggest competitors for a brand Source: https://docs.otterly.ai/api-reference/competitors/suggest-competitors-for-a-brand https://data.otterly.ai/v1/openapi.json post /v1/competitors/suggestions Suggests competitors for a brand using AI web search, with name variations and domain variations for each. Nothing is saved. Every item is ready to pass as a competitor to `POST /v1/reports/brand` or `PATCH /v1/reports/brand/{reportId}`. The brand own domain is never returned. A 503 means the research failed or timed out and the request is safe to retry. # List AI engines and supported countries Source: https://docs.otterly.ai/api-reference/engines/list-ai-engines-and-supported-countries https://data.otterly.ai/v1/openapi.json get /v1/engines # Create prompts in a workspace Source: https://docs.otterly.ai/api-reference/prompts/create-prompts-in-a-workspace https://data.otterly.ai/v1/openapi.json post /v1/workspaces/{id}/prompts Creates one prompt (`prompt`) or several (`prompts`) in the workspace and starts monitoring them, exactly like creation in the UI (including search-volume computation). Up to 5 prompts are created synchronously (201 with the created items); larger batches are processed asynchronously (202 with a processing summary). The whole batch is validated against the workspace's remaining prompt allocation up front — nothing is created if it would exceed the limit. # Delete a prompt Source: https://docs.otterly.ai/api-reference/prompts/delete-a-prompt https://data.otterly.ai/v1/openapi.json delete /v1/workspaces/{id}/prompts/{promptId} Deletes the prompt. It is removed from any brand report it is part of, and affected brand reports are recalculated without it (asynchronously). # List prompts in a workspace Source: https://docs.otterly.ai/api-reference/prompts/list-prompts-in-a-workspace https://data.otterly.ai/v1/openapi.json get /v1/workspaces/{id}/prompts Lists the prompts monitored in the workspace. `id` is the identifier accepted by the prompt write endpoints. # Update the tags assigned to a prompt Source: https://docs.otterly.ai/api-reference/prompts/update-the-tags-assigned-to-a-prompt https://data.otterly.ai/v1/openapi.json patch /v1/workspaces/{id}/prompts/{promptId} Replaces the prompt's tag assignments with the provided set. A prompt's text and country are immutable — requests attempting to change them are rejected; create a new prompt instead. # Create a tag in a workspace Source: https://docs.otterly.ai/api-reference/tags/create-a-tag-in-a-workspace https://data.otterly.ai/v1/openapi.json post /v1/workspaces/{id}/tags # Delete a tag Source: https://docs.otterly.ai/api-reference/tags/delete-a-tag https://data.otterly.ai/v1/openapi.json delete /v1/workspaces/{id}/tags/{tagId} Deletes the tag. The tag is unassigned from all prompts asynchronously; brand reports filtered by it update accordingly. # List tags for a workspace Source: https://docs.otterly.ai/api-reference/tags/list-tags-for-a-workspace https://data.otterly.ai/v1/openapi.json get /v1/workspaces/{id}/tags # List workspaces Source: https://docs.otterly.ai/api-reference/workspaces/list-workspaces https://data.otterly.ai/v1/openapi.json get /v1/workspaces # Authentication Source: https://docs.otterly.ai/authentication How to authenticate requests to the OtterlyAI Public API The OtterlyAI Public API uses **Bearer token** authentication. Every request (except `/v1/health`, `/v1/openapi.json`, and `/v1/docs`) must include an `Authorization` header. ## Header Format ``` Authorization: Bearer oai_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ## Generating an API Key 1. Sign in to the [OtterlyAI dashboard](https://app.otterly.ai). 2. Open **Settings → API Keys**. 3. Click **Create API key**, choose the workspaces and permissions, then copy the generated key. You will only see it once. ## Permissions API keys are scoped to: * **Workspaces** — only data inside the granted workspaces is returned. * **Permissions** — typically `read` for data retrieval endpoints. A request with an insufficient permission set receives a `403 Forbidden` response. ## Errors | Status | Meaning | | - | - | | `401` | Missing or invalid `Authorization` header | | `403` | Key lacks the required permission or workspace access | | `429` | Rate limit exceeded | # Claude Skill Source: https://docs.otterly.ai/claude-skill Use OtterlyAI directly inside Claude with the OtterlyAI skill The OtterlyAI Claude Skill lets you query your brand visibility data — reports, citations, prompts, recommendations, and GEO audits — directly from Claude. ## Installation 1. [Download the `otterly.skill` file](https://otterly-skills.s3.eu-central-1.amazonaws.com/otterly.skill). 2. Open **Claude Desktop**. 3. Go to **Customize → Skills → + → Create Skill → Upload Skill** and select the file. The skill is automatically available in all new Claude sessions after installation. > [!TIP] > > You can also install via the CLI if you prefer: > > ```bash theme={null} > claude skill add /path/to/otterly.skill > ``` ## Allow the OtterlyAI Domain Before using the skill, you need to allow `data.otterly.ai` in Claude's domain allowlist. Go to **Claude Settings → Capabilities** and add `data.otterly.ai` to the **Domain allowlist**. ![Claude Capabilities — Domain allowlist](https://mintcdn.com/otterlyai/bqqenwWEQnCboDkb/downloads/capabilities.png?fit=max\&auto=format\&n=bqqenwWEQnCboDkb\&q=85\&s=402af3df022a097be3ef56fcde2bbdcf) Add data.otterly.ai to the Domain allowlist in Claude Settings → Capabilities ## Setting Your API Key The skill needs an `OTTERLY_API_KEY` to authenticate against the OtterlyAI Public API. There are two ways to provide it: ### Option 1: Set it per session At the start of each Claude Code session, simply tell Claude your API key: ``` My OtterlyAI API key is oai_live_xxxx... ``` Claude will remember it for the duration of the session. This is the safest option — your key is never persisted to disk. ### Option 2: Store it in the skill You can edit the skill itself to include your API key permanently. Ask Claude to do it for you: ``` Edit the OtterlyAI skill and set the OTTERLY_API_KEY to oai_live_xxxx... ``` Claude will update the skill's configuration so the key is available automatically in every future session. This is more convenient but means the key is stored locally on your machine. > [!WARNING] > > Only store your API key in the skill on devices you trust. If your machine is > shared, prefer the per-session approach. ## Generating an API Key If you don't have an API key yet: 1. Sign in to the [OtterlyAI dashboard](https://app.otterly.ai). 2. Go to [API Keys](https://app.otterly.ai/api-keys). 3. Click **Create API key**, choose the workspaces and permissions, then copy the key. You will only see it once. > [!NOTE] > > A **read-only** key is sufficient for accessing brand reports, prompts, > citations, and recommendations. To perform GEO audits or other write > operations, you need a key with **read and write** permissions. ## What You Can Do Once the skill is active, just ask Claude naturally. For example: * *"How's my brand doing?"* — get a summary of your brand visibility stats * *"Which prompts mention my brand the most?"* — ranked prompt analysis * *"Are AI bots blocked from my site?"* — crawlability audit * *"Show me what ChatGPT said about \[topic]"* — view actual AI engine responses * *"Run a content audit on [https://example.com](https://example.com)"* — trigger an on-demand GEO audit * *"Compare my brand visibility this month vs last month"* — period comparison The skill covers the full OtterlyAI Public API, including workspaces, brand reports, KPIs, citations, prompts, recommendations, and GEO audits (crawlability + content). # Introduction Source: https://docs.otterly.ai/introduction Welcome to the OtterlyAI Public API The OtterlyAI Public API lets you programmatically access brand reports, prompts, citations, agent analytics (AI crawler traffic on your own domains), user analytics (the visitors AI assistants send to your site), and workspace data from the OtterlyAI platform. ## Base URL ``` https://data.otterly.ai ``` All endpoints are prefixed with `/v1`. ## OpenAPI Spec The full machine-readable spec is published at: ``` https://data.otterly.ai/v1/openapi.json ``` This documentation is generated directly from that spec, so it is always in sync with the deployed API. ## Quick Start 1. Generate an API key from your [OtterlyAI dashboard](https://app.otterly.ai/api-keys). 2. Send it as a Bearer token in the `Authorization` header. 3. Call any endpoint listed in the API Reference. ```bash theme={null} curl https://data.otterly.ai/v1/health \ -H "Authorization: Bearer YOUR_API_KEY" ``` # OtterlyAI MCP Server Source: https://docs.otterly.ai/mcp-server Use OtterlyAI with Model Context Protocol (MCP)–compatible clients The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) lets AI assistants like Claude Code, Claude Desktop, Cursor, and other compatible clients call external tools in a structured way. The OtterlyAI MCP server exposes your brand reports, prompts, citations, recommendations, and audit checks as MCP tools so your assistant can answer questions about your AI search visibility directly. ## Endpoint ``` https://data.otterly.ai/mcp ``` The server speaks the MCP **streamable HTTP** transport. Authentication is handled entirely through **OAuth 2.0** — see below. ## Authentication The OtterlyAI MCP server authenticates with **OAuth 2.0**. You do **not** pass an API key. When you add the server to a compatible client, the client walks you through a standard browser sign-in to OtterlyAI and obtains an access token on your behalf. Permissions and workspace scoping match your OtterlyAI account. > [!NOTE] > > The `oai_live_` API keys documented under > [Authentication](/authentication) are for the **REST Public API only**. The > MCP server does not accept them — it is OAuth-only. The flow is fully automatic for MCP clients: there is nothing to configure by hand. Under the hood the server implements OAuth 2.0 with dynamic client registration and PKCE, and advertises discovery metadata at: ``` https://data.otterly.ai/.well-known/oauth-protected-resource/mcp https://data.otterly.ai/.well-known/oauth-authorization-server ``` When a request arrives without a valid token, the server responds `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata, which is the client's cue to start the OAuth flow. ## Quick sanity check You don't need a token to confirm the server is up and correctly OAuth-gated. An unauthenticated request returns `401` with a `WWW-Authenticate` header: ```bash theme={null} curl -i https://data.otterly.ai/mcp -X POST \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' ``` You should see `HTTP/1.1 401` and a header of the form `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://data.otterly.ai/.well-known/oauth-protected-resource/mcp"`. Fetching that metadata document returns the resource and its authorization server: ```bash theme={null} curl https://data.otterly.ai/.well-known/oauth-protected-resource/mcp ``` ## Claude.ai In **Customize → Connectors**, choose **Add connector / "+" sign**, search for OtterlyAI, and click **Connect**: ``` https://data.otterly.ai/mcp ``` A browser window opens to sign in to OtterlyAI and authorize access. Once approved, the OtterlyAI tools are available in your chats. Claude.ai holds the resulting token itself, so it never shares credentials with another client on your machine. ## Claude Code ```bash theme={null} claude mcp add --transport http otterly https://data.otterly.ai/mcp ``` The first time a tool is used, Claude Code opens a browser to complete the OAuth sign-in. Verify with `claude mcp list` — you should see `otterly: ... - ✓ Connected`. Tools are then available as `mcp__otterly__`. Claude Code holds the resulting token itself, so it never shares credentials with another client on your machine. ## Claude Desktop Add a remote connector pointing at the endpoint; Claude Desktop runs the OAuth flow in your browser on first connect. If your version launches stdio servers only, use the [`mcp-remote`](https://github.com/geelen/mcp-remote) bridge — it performs the OAuth handshake for you, so **no static `Authorization` header is needed**. Add the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS): ```json theme={null} { "mcpServers": { "otterly": { "command": "npx", "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp"] } } } ``` Restart Claude Desktop; a browser opens to authorize, and the OtterlyAI tools appear in the tool picker. > [!WARNING] > > If you also run Cursor, a second Claude Desktop profile, or any other > `mcp-remote` client on this machine, the snippet above is not enough — see > [Running more than one client](#running-more-than-one-client-on-one-machine). ## Cursor In **Cursor → Settings → MCP**, add a new server using the same `mcp-remote` bridge (the OAuth flow opens in your browser on first use): ```json theme={null} { "mcpServers": { "otterly": { "command": "npx", "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp"] } } } ``` > [!WARNING] > > If you also run Claude Desktop or any other `mcp-remote` client on this > machine, the snippet above is not enough — see > [Running more than one client](#running-more-than-one-client-on-one-machine). ## Running more than one client on one machine The `mcp-remote` bridge stores every credential in `~/.mcp-auth`, keyed by server URL, regardless of which client started it. Two clients pointed at the same URL therefore share a single login: whichever one authorizes last evicts the other, which then opens its own browser tab to authorize and evicts the first. The symptom is an authorization tab that keeps reappearing and a client that reports no connection to OtterlyAI. Separate application folders do not separate these credentials — two Claude Desktop profiles hit this too. Give each client its own store and its own callback port. Claude Desktop: ```json theme={null} { "mcpServers": { "otterly": { "command": "npx", "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp", "9696"], "env": { "MCP_REMOTE_CONFIG_DIR": "/Users/you/.mcp-auth-claude" } } } } ``` Cursor: ```json theme={null} { "mcpServers": { "otterly": { "command": "npx", "args": ["-y", "mcp-remote", "https://data.otterly.ai/mcp", "9697"], "env": { "MCP_REMOTE_CONFIG_DIR": "/Users/you/.mcp-auth-cursor" } } } } ``` Use an absolute path for `MCP_REMOTE_CONFIG_DIR`; `~` is not expanded. Then quit every client, delete the shared `~/.mcp-auth`, and authorize one client at a time. This is also how you connect two different OtterlyAI accounts on one machine — with one shared store both clients end up on whichever account authorized last. ## Available tools Every tool has a counterpart in the [Public API](https://data.otterly.ai/v1/openapi.json) and returns the same data shapes. Each tool also advertises an `outputSchema` (JSON Schema) in `tools/list` and returns its result as `structuredContent` conforming to that schema, with the same JSON mirrored in the `text` block — so clients can type and validate responses at the protocol level. Required arguments are listed per tool; optional arguments below the tables. ### Account | Tool | Required arguments | Description | | - | - | - | | `get_account_info` | — | Your team's subscription plan and end date, plus current-period usage and limits for prompts, GEO audits, Public API requests, and MCP tool calls. Free: it never counts against the MCP limit and works even once the limit is reached. | ### Workspaces & engines | Tool | Required arguments | Description | | - | - | - | | `list_workspaces` | — | List all workspaces accessible by the API key. | | `list_workspace_tags` | `workspaceId` | List tags defined for a workspace, with their color and prompt count. | | `list_workspace_prompts` | `workspaceId` | List the prompts monitored in a workspace. `id` is the identifier accepted by the prompt write tools. | | `list_engines` | — | List available AI engines and their supported countries. Optional filters: `country`, `engine`. | ### Brand reports | Tool | Required arguments | Description | | - | - | - | | `list_brand_reports` | — | List brand reports accessible by the API key. Optional `workspaceId` scopes to a single workspace. | | `get_brand_report` | `reportId` | Get a brand report's details, including competitors, countries, and tags. | | `get_brand_report_stats` | `reportId`, `startDate`, `endDate`, `country` | Aggregated stats — brand coverage history, brand ranks with sentiment, top domains, and engine breakdown. | | `list_brand_report_prompts` | `reportId`, `startDate`, `endDate`, `country` | List prompts with brand and domain mention stats for a date range and country. | | `get_brand_report_prompt` | `reportId`, `promptId`, `startDate`, `endDate`, `country` | Detailed metrics for a single prompt — brand coverage history, ranks, sentiment, domain categories, tags. | | `list_brand_report_prompt_ai_responses` | `reportId`, `promptId`, `startDate`, `endDate`, `country` | List AI response runs collected for a prompt — raw model content, brand mentions, and citations. | | `list_brand_report_citations` | `reportId`, `startDate`, `endDate`, `country` | List cited URLs for a brand report, filterable by AI engine, tag, and search query. | | `get_brand_report_citation_stats` | `reportId`, `startDate`, `endDate`, `country` | Citation stats — top cited domains, share-of-citations, and most-cited URLs over a date window. | | `list_brand_report_citation_prompts` | `reportId`, `url`, `startDate`, `endDate`, `country` | List prompts that cited a specific URL within a brand report over a date window. | | `get_brand_report_citation_history` | `reportId`, `url`, `startDate`, `endDate`, `country` | Get Citation history for a cited URL — total citations, the change vs the previous period (`percentageChange`), and a daily breakdown by engine. | | `list_brand_report_recommendations` | `reportId`, `country` | List AI-generated recommendations for improving brand visibility, optionally filtered by `engine`. | | `list_brand_report_annotations` | `reportId` | List the annotations (dated notes and recommendation markers) on a brand report's charts, most recently created first. Optional `startDate` + `endDate` (both or neither) narrow it to annotations dated in that range, inclusive, ordered by annotation date, latest first. Annotations may not show in the dashboard until annotations are enabled there. | | `research_competitors` | `brand`, `brandDomain` | Suggest competitors for a brand from one web-backed AI lookup. Optional: `maxResults` (default 10, max 20). Returns them in the exact shape `create_brand_report` and `update_brand_report` accept for `competitors`, with likely name variations and extra domains, subdomains included. The input brand is never returned. Nothing is saved: review the list, then pass it on. Counts as one normal call. | ### Agent analytics AI crawler and agent traffic hitting the brand report's own domains — the inverse of citations, which are what the engines said about your brand. Same data as the Agent Analytics tab in the app. | Tool | Required arguments | Description | | - | - | - | | `get_brand_report_agent_stats` | `reportId` | Overview of agent traffic — total agent visits, distinct pages visited, the busiest engine, per-engine totals, and a per-(day, engine, bot) visit series (`trend`). | | `list_brand_report_agent_pages` | `reportId` | Per-URL breakdown, busiest page first, with a per-engine split. Supports `search` on the page URL and `agent` (agent names). | | `list_brand_report_agents` | `reportId` | Per-agent breakdown — agent name, its engine, its category (`On-Demand AI Fetcher`, `Search Index`, `AI Training / Data Scraper`, or `Other`), and visit count. Supports `search` and `agent`. | Unlike the other brand-report tools, `startDate` and `endDate` are **optional** here and default to the last 14 days (UTC) — the window the app shows by default. There is no `country` argument: crawler traffic is attributed to a URL and a user-agent, and neither carries a country. `get_brand_report_agent_stats` speaks one engine vocabulary throughout — `chatgpt`, `claude`, `copilot`, `perplexity`, `google` (Gemini included), `other`. That holds for both the summary (`topEngine`, per-engine totals) and the `trend` series, whose rows are `{ dayId, engine, bot, visitCount }`. `bot` is the raw crawler name (`GPTBot`, `Google-Extended`), so one engine can appear across several bots on a day — e.g. `google` for both `GoogleOther` and `Google-Extended`. Every response carries an `availability` field. Check it before reading the numbers: | `availability` | Meaning | | - | - | | `not_connected` | No logs connector is set up for this report. Metrics are **`null`, not zero** — nothing is being measured. Connect a log source in the app first. | | `connected_no_data` | A connector is active but matched no visits in this window. The zeros are real. | | `connected_with_data` | Populated payload. | Treating `not_connected` as zero is the mistake worth avoiding: it reads as "no AI crawler visited this site" when the truth is that nobody is measuring. ### User analytics Human visitors to the brand report's own domains, measured by the User Analytics snippet installed on the site, and which AI assistant sent them. Same data as the User Analytics tab in the app. | Tool | Required arguments | Description | | - | - | - | | `get_user_analytics_stats` | `reportId` | Overview of user traffic — total visits, unique visitors, distinct pages visited, the top source, per-source totals, and a per-(day, source) visit series (`trend`). Optional `source`, `country`. | | `list_user_analytics_pages` | `reportId` | Per-page breakdown, busiest page first, with a per-source split. Pages are per host, so a subdomain's pages are listed on their own. Supports `search` on ``, `source`, `country`. | | `list_user_analytics_countries` | `reportId` | Per-country breakdown, busiest country first. Supports `source`. Returns the codes `country` accepts on the other two tools. | Like the agent-analytics tools, `startDate` and `endDate` are **optional** and default to the last 14 days (UTC). They take `YYYY-MM-DD` only, no time part, and the day has to exist: `2026-02-29` is refused rather than rolled over. A **source** is where the visitor came from: an AI assistant (`openai`, `perplexity`, `google`, `microsoft`, `anthropic`, …), `other_external` (another website), `direct_none` (no referrer) or `internal_self` (another page of the same site). `source` on these tools takes one value. Omitted, it means the AI assistants only, as in the app, so the totals match the User Analytics tab. Named, it returns that one source alone (`direct_none` is direct visits only), so a total across sources takes one call per source. The stats response lists every source that had visits within that filter. `country` is the visitor's country in the usual spelling (`us`, `de`, `uk`), plus `zz` for the visits whose country could not be determined. One value per call; `list_user_analytics_countries` lists the countries with data. `uniqueVisitors` counts a visitor once across the window even when they return on another day. It is `null`, not zero, when it could not be computed: the window starts more than about 13 months back (the raw events behind it are kept 13 months; the daily totals are kept longer), or the count ran out of time. The rest of the payload still stands. Narrow the window to fill it; retrying the same call does not help when the start is past that floor. The responses carry the same `availability` field as the agent-analytics tools, with one difference in what `not_connected` means: no User Analytics site is set up for this report (none has gone past `pending`). A site that was later disabled still counts — what it collected stays readable. Metrics are `null`, not zero, while `not_connected`. Under the default `source`, `connected_no_data` means no AI-referred visits in the window, not no visits at all; an empty countries list reads the same way. ### GEO audits | Tool | Required arguments | Description | | - | - | - | | `list_crawlability_checks` | `workspaceId` | List crawlability audit checks (robots.txt analysis, bot access) for a workspace. | | `get_crawlability_check` | `checkId`, `workspaceId` | Get a crawlability check's full results. | | `list_content_checks` | `workspaceId` | List content / AI-readiness checks for a workspace. | | `get_content_check` | `checkId`, `workspaceId` | Get a content check's full results — AI readiness, PageSpeed, structural and dynamic-content scores. | ### Query fan-outs | Tool | Required arguments | Description | | - | - | - | | `list_query_fan_outs` | `workspaceId` | List query fan-out runs for a workspace — each run expands an original query into the related queries AI search engines may generate. | | `get_query_fan_out` | `fanOutId`, `workspaceId` | Get a query fan-out run and its expanded queries (query, type, user intent, reasoning) split per AI engine. | ### Write tools (`write` permission only) | Tool | Required arguments | Description | | - | - | - | | `create_crawlability_check` | `workspaceId`, `url` | Create a new crawlability audit for a URL. | | `create_content_check` | `workspaceId`, `url` | Create a new content / AI-readiness check. Optional: `crawlerIdentity` (crawler user-agent to test the page against), `sendOtterlyHeader` (send identity header). | | `create_query_fan_out` | `workspaceId`, `query` | Generate a new query fan-out — expands an original query into related queries across AI engines. Runs asynchronously; poll `get_query_fan_out` until status is `completed` or `failed`. | | `create_prompts` | `workspaceId`, `country`, `prompts` | Create one or more prompts in a workspace and start monitoring them, exactly like creation in the UI. Optional: `tagIds`, `brandReportIds`. Up to 5 prompts are created synchronously and returned with their IDs; larger batches are processed asynchronously and return a processing summary instead — use `list_workspace_prompts` afterward to see what was created. The whole batch is validated against the workspace's remaining prompt allocation up front. A prompt's `text` and `country` are immutable after creation. | | `delete_prompt` | `workspaceId`, `promptId` | Delete a prompt. It's removed from any brand report it's part of, and affected brand reports are recalculated without it (asynchronously). | | `update_prompt_tags` | `workspaceId`, `promptId`, `tagIds` | Replace the tags assigned to a prompt with the given set (pass `[]` to remove all tags). Only tags can be changed — attempting to change a prompt's text or country isn't supported; create a new prompt and delete the old one instead. | | `create_brand_report` | `workspaceId`, `promptIds`, `brandDomain` | Create a brand report from prompts that already exist in the workspace (at least one). Set `brand`, or `brandRegex` with `reportTitle`. Optional: `brand`, `reportTitle`, `brandVariations`, `brandRegex`, `brandDomainWildcard`, `brandDomainVariations`, `competitors`. `brandRegex` replaces `brand` + `brandVariations` for detection (JavaScript-compatible, case-sensitive, max 1000 characters); send one or the other, not both. With `brandRegex` you can leave out `brand`, but then `reportTitle` is required and is used as the brand's label. `brandDomainWildcard` includes all subdomains of the main domain only. Each competitor takes the same brand fields, and its `brand` is always required as its label. Up to 100 competitors, and up to 100 name and domain variations each. Countries come from the prompts. Returns the full report, in the same shape as `get_brand_report`. | | `update_brand_report` | `reportId` | Update a brand report. Takes any of the `create_brand_report` fields except `workspaceId`, and only the fields you send change. Array fields (`promptIds`, `competitors`, `brandVariations`, `brandDomainVariations`) replace the stored list whole. Send `brandRegex: null` to remove a regex, together with `brand`. You can send back a report from `get_brand_report` unchanged; read-only fields are ignored. Lists are capped at 100 competitors and 100 variations each. Changing a detection field (brand, variations, regex, domains, competitors) recalculates the report's existing history asynchronously, not only future runs. Returns the full updated report. | | `add_prompts_to_brand_report` | `reportId`, `promptIds` | Add one or more existing prompts to a brand report, up to 1000 per call. Prompts already on the report are ignored rather than duplicated, and the response lists which ids were added and which were already assigned. The report is recalculated asynchronously to include the new prompts. There's no `workspaceId` argument — the workspace is taken from the report. | | `remove_prompts_from_brand_report` | `reportId`, `promptIds` | Remove one or more prompts from a brand report, up to 1000 per call. The prompts themselves aren't deleted; they stay in the workspace and only their membership of the report goes away, and the report is recalculated without them (asynchronously). Removing a prompt discards the citation data already collected for it in that report: if you add it back later, only the most recent 7 days of its citation history are reprocessed and anything older isn't restored, so removing and re-adding isn't reversible. | | `create_tag` | `workspaceId`, `name`, `color` | Create a new tag in a workspace. Tags can be assigned to prompts with `update_prompt_tags`. | | `delete_tag` | `workspaceId`, `tagId` | Delete a tag. It's unassigned from all prompts asynchronously; brand reports filtered by it update accordingly. | | `create_brand_report_annotation` | `reportId`, `date`, `text` | Add a note to a brand report, dated `date` (`YYYY-MM-DD`), with `text` of 1 to 1000 characters after trimming. Optional `type` accepts only `note`: only notes can be created; recommendation markers come from completing a recommendation in the app. Annotations may not show in the dashboard until annotations are enabled there. | | `update_brand_report_annotation` | `reportId`, `annotationId` | Change a note's `text` (1 to 1000 characters after trimming) and/or `date` (at least one). You can send back an item from `list_brand_report_annotations` unchanged; read-only fields are ignored. Recommendation annotations can't be edited. | | `delete_brand_report_annotation` | `reportId`, `annotationId` | Delete a note or a recommendation annotation, which removes it from the chart. Deleting it again returns "Annotation not found". | These tools are only registered when your account has `write` permission; with read-only access they are not advertised by the server. ### Common arguments * **Dates**: `startDate` and `endDate` are inclusive and take `YYYY-MM-DD` only; a full ISO timestamp is refused on every tool. On the agent- and user-analytics tools they are optional and default to the last 14 days (UTC). * **Country**: `country` is a lowercase ISO 3166-1 alpha-2 code (e.g. `us`, `de`). Use `uk` for the United Kingdom. * **Engines**: `engines` (multi-value) and `engine` (single-value) accept `chatgpt`, `claude`, `google`, `perplexity`, `copilot`, `google_ai_mode`, `gemini`. Call `list_engines` to see which engines are available in which countries. * **Engines on the agent-analytics tools**: single-value — `chatgpt`, `claude`, `copilot`, `perplexity`, `google`, `other`. `google` covers the whole Google family (Gemini included), unlike the app which lists Gemini separately. Pass `engine=other` to match every AI crawler outside the named engines (Amazon, Meta, xAI, ByteDance, Common Crawl, and so on). `other` also appears in the response breakdown, so it means the same thing in and out. The agent name in `list_brand_report_agents` is always exact, so `other` never hides which crawler it was. * **Pagination**: every list tool pages, with `limit` defaulting to `25` (max `100`). The `paging` object has the same shape as the Public API endpoint behind the tool, but only the shape: several Public API endpoints return the whole list in one response where MCP pages it. Cursor lists (`list_workspaces`, `list_workspace_tags`, `list_workspace_prompts`, `list_brand_reports`, `list_brand_report_recommendations`, `list_brand_report_annotations`, `list_crawlability_checks`, `list_content_checks`, `list_query_fan_outs`) accept `cursor` and `limit` and return `paging: { nextCursor, hasMore }`; pass `nextCursor` back as `cursor` for the next page. `list_brand_report_prompt_ai_responses` is cursor-paged too, with `cursor` only. Offset lists (`list_brand_report_citations`, `list_brand_report_prompts`, `list_brand_report_citation_prompts`, `list_brand_report_agent_pages`, `list_brand_report_agents`, `list_user_analytics_pages`, `list_user_analytics_countries`) accept `limit` and `offset` (a multiple of `limit`) and return `paging: { limit, offset, hasMore }`, the agent-analytics and user-analytics lists adding `totalCount`; add `limit` to `offset` for the next page. Either way, stop when `hasMore` is `false`. The former `page` and `pageSize` arguments are no longer accepted: a list tool rejects them, like any unknown argument, with a validation error rather than ignoring them. * **Extra filters on `list_brand_report_prompts` and `list_brand_report_citations`**: `engines`, `tagId`, `search`, `sortBy`, `sortOrder`. * **`search` on the agent-analytics list tools** is a case-insensitive substring match, applied server-side across the whole result set. It is matched literally — `%` and `_` are not wildcards. * **`agent` on the agent-analytics list tools** is a list of agent names as `list_brand_report_agents` returns them (`GPTBot`, `Claude-User`), matched whole and case-insensitively. It narrows together with `engine` and `search`, so `engine=claude` with `agent=["GPTBot"]` is an empty page, not an error. A name `list_brand_report_agents` never returned is not rejected either: it matches nothing, so a misspelling reads as no traffic. Omit `agent` for no filter — an empty list fails with a validation error. Use it to tell apart agents that share an engine — for example `Claude-User` (on-demand fetches) from `ClaudeBot` (training crawls) under `claude`. * **`source` and `country` on the user-analytics tools**: single-value. `source` is a visitor source (`openai`, `perplexity`, `google`, `microsoft`, `anthropic`, `other_external`, `direct_none` or `internal_self`), matched whole and case-insensitively; an unknown name matches nothing. Omitted, the AI assistants; named, that source alone. `country` is the usual lowercase code, with `zz` for visits whose country is unknown. `search` on `list_user_analytics_pages` works like the agent-analytics one, on ``; a full URL is accepted. ## Typical conversation flow 1. `get_account_info` → your plan and how many MCP tool calls remain this period. Free, so it is safe to call first. 2. `list_workspaces` → pick a `workspaceId` (optional). 3. `list_brand_reports` → pick a `reportId`. 4. `list_brand_report_prompts` or `list_brand_report_citations` with `reportId`, a date range, and a country code (e.g. `us`, `uk`, `de`). 5. Drill into `get_brand_report_stats`, `get_brand_report_citation_stats`, `list_brand_report_recommendations`, or the GEO audit tools as needed. 6. To ask about AI crawlers on your own site rather than what the engines said, start at `get_brand_report_agent_stats` with just the `reportId`, then drill into `list_brand_report_agent_pages` or `list_brand_report_agents`. 7. To ask about the people AI assistants send to your site, start at `get_user_analytics_stats` with just the `reportId`, then drill into `list_user_analytics_pages` or `list_user_analytics_countries`. ## Troubleshooting **The authorization tab keeps reopening, or the client reports no connection to OtterlyAI.** Two clients are sharing one `mcp-remote` credential store — see [Running more than one client](#running-more-than-one-client-on-one-machine). Reconnecting repairs one client and breaks the other, so the loop survives any number of reconnects. **"state already in use".** A connection link is single-use and retrying the same one lands here. Wait about ten minutes, then start the connection again from the client rather than reloading the page. **The wrong OtterlyAI account got connected.** Approval is granted by whichever account the browser is already signed into; the client has no say in it. To connect a specific account, sign that account in first — a separate browser profile per account is the reliable way — and then authorize. **`401` from a tool call.** The OAuth token is missing or expired; reconnect to refresh it. If reconnecting works and then fails again within a day, it is the shared-credential case above rather than an expiry. **`403` from a tool call.** Your account lacks permission for the requested workspace. ## Things to know * Most tools are **read-only**. The tools in the **Write tools** section above are only available to accounts with the `write` permission. * Workspace scoping matches your OtterlyAI account. See [Troubleshooting](#troubleshooting) for `401` and `403` responses. * Every tool call except `get_account_info` counts against your plan's MCP tool-call limit. Once it is exhausted, calls fail with `Request limit exceeded for this billing period` until the next period. * Each tool's `outputSchema` is the contract for its result. The shapes are the Public API response shapes, paging included, so the [OpenAPI spec](https://data.otterly.ai/v1/openapi.json) doubles as a field reference. > [!TIP] > > Hitting a bug or missing a tool you'd like to see? Email > [support@otterly.ai](mailto:support@otterly.ai).