### Quickstart: Check Mentions with MentionsAPI

Source: https://mentionsapi.com/docs/sdks/python

Initialize the MentionsAPI client with your API key and perform a check for mentions. This example demonstrates how to retrieve citations from the 'perplexity' provider.

```python
import os
from mentionsapi import MentionsAPI

client = MentionsAPI(api_key=os.environ["MENTIONSAPI_KEY"])

result = client.check(
    mode="all_live",
    query="best CRM for small business",
    brand="HubSpot",
)

print(result.providers["perplexity"].citations)
```

--------------------------------

### Quickstart cURL Example for POST /v1/check

Source: https://mentionsapi.com/docs/api/check

This cURL command demonstrates how to make a basic request to the /v1/check endpoint to find mentions of a brand in a given query. It uses the 'quick' mode by default.

```bash
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live-..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "quick",
    "query": "best CRM for small business",
    "brand": "HubSpot"
  }'
```

--------------------------------

### Quickstart: Check Mentions with Node.js SDK

Source: https://mentionsapi.com/docs/sdks/node

Initialize the MentionsAPI client with your API key and perform a check for mentions. This example demonstrates fetching mentions for a specific query and brand.

```javascript
import { MentionsAPI } from "@mentionsapi/sdk";

const client = new MentionsAPI({ apiKey: process.env.MENTIONSAPI_KEY! });

const result = await client.check({
  mode: "all_live",
  query: "best CRM for small business",
  brand: "HubSpot",
});

console.log(result.providers.perplexity.citations);
```

--------------------------------

### Python SDK Usage Example

Source: https://mentionsapi.com/docs/sdks

Example of using the Python SDK to interact with the MentionsAPI. Ensure the MENTIONSAPI_KEY environment variable is set. The SDK is currently available by installing locally from the repository.

```python
# pip install mentionsapi  (forthcoming on PyPI)
# Today: clone packages/sdk-python and install locally.

import os
from mentionsapi import MentionsAPIClient

client = MentionsAPIClient(api_key=os.environ["MENTIONSAPI_KEY"])

res = client.ask(
    prompt="Best PostgreSQL hosting in 2026?",
    providers=["openai", "anthropic", "perplexity"],
    track_brands=["Supabase", "Neon"],
    web_search=True,
)

for p in res["providers"]:
    if "error" in p:
        print(p["provider"], "failed:", p["error"]["code"])
    else:
        print(p["provider"], "→", p["content"][:120])

print("cost:", res["usage"]["cost_cents"], "cents")
```

--------------------------------

### Install Node.js SDK

Source: https://mentionsapi.com/docs/sdks/node

Install the @mentionsapi/sdk package using npm, pnpm, or yarn.

```APIDOC
## Install Node.js SDK

Install the @mentionsapi/sdk package using npm, pnpm, or yarn.

### Method

```bash
npm install @mentionsapi/sdk
# or pnpm / yarn
pnpm add @mentionsapi/sdk
yarn add @mentionsapi/sdk
```
```

--------------------------------

### Install @mentionsapi/sdk

Source: https://mentionsapi.com/docs/sdks/node

Install the Node.js SDK using npm, pnpm, or yarn. Ensure your Node.js version is 18 or higher.

```bash
npm install @mentionsapi/sdk
# or pnpm / yarn
pnpm add @mentionsapi/sdk
yarn add @mentionsapi/sdk
```

--------------------------------

### Quickstart: Check Mentions

Source: https://mentionsapi.com/docs/sdks/node

Initialize the SDK client and perform a basic mention check.

```APIDOC
## Quickstart: Check Mentions

Initialize the SDK client and perform a basic mention check.

### Method

```javascript
import { MentionsAPI } from "@mentionsapi/sdk";

const client = new MentionsAPI({ apiKey: process.env.MENTIONSAPI_KEY! });

const result = await client.check({
  mode: "all_live",
  query: "best CRM for small business",
  brand: "HubSpot",
});

console.log(result.providers.perplexity.citations);
```
```

--------------------------------

### Install MentionsAPI Python SDK

Source: https://mentionsapi.com/docs/sdks/python

Install the MentionsAPI Python SDK using pip. You can also use package managers like uv or poetry.

```bash
pip install mentionsapi
# or with uv / poetry
uv add mentionsapi
poetry add mentionsapi
```

--------------------------------

### Install @mentionsapi/sdk for Node.js

Source: https://mentionsapi.com/docs/sdks

Install the official Node.js SDK using npm, pnpm, or bun. This package provides typed request/response shapes and built-in retry logic.

```bash
# npm
npm install @mentionsapi/sdk

# pnpm
pnpm add @mentionsapi/sdk

# bun
bun add @mentionsapi/sdk
```

--------------------------------

### Install Local MCP Server with npm

Source: https://mentionsapi.com/docs/mcp

Install the MentionsAPI MCP server locally using npx. Replace 'lvk_live_...' with your actual MentionsAPI key obtained from /app/keys. This server acts as a wrapper for the REST API.

```bash
npx -y @mentionsapi/mcp@latest --api-key=lvk_live_...
```

--------------------------------

### Rate Limit Headers Example

Source: https://mentionsapi.com/docs/errors

Example of rate limit headers that are emitted on every authenticated response.

```http
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
Retry-After: 2
```

--------------------------------

### Perplexity Live Mode Response Example

Source: https://mentionsapi.com/docs/api/check/mode-perplexity-live

This is an example of the JSON response you can expect when using the `perplexity_live` mode. It includes details about the mentioned provider, context, citations, and fan-out queries.

```json
{
  "id": "chk_a8d2c...",
  "mode": "perplexity_live",
  "providers": {
    "perplexity": {
      "mentioned": true,
      "rank": 6,
      "context": "If you want a free-tier and strong sales/marketing features: HubSpot CRM (free plan; scales with paid add-ons). Great for startups...",
      "citations": [
        { "url": "https://zapier.com/blog/best-crms-for-small-business/", "title": "The 12 best CRMs for small business - Zapier" },
        { "url": "https://www.softwareadvice.com/crm/", "title": "CRM Software Reviews" },
        { "url": "https://www.g2.com/categories/crm", "title": "G2 CRM" }
      ],
      "fan_out": [
        "What features matter most for my small business CRM",
        "CRM comparisons by price for small businesses in 2026",
        "Top CRM for startups with limited budgets",
        "CRM vs ERP: what does a small business need",
        "Reviews of popular small business CRMs this year"
      ]
    }
  },
  "duration_ms": 25102,
  "cost_cents": 25,
  "cache_hit": false
}
```

--------------------------------

### Search Mentions Example

Source: https://mentionsapi.com/docs/endpoints/mentions

Example of how to search for mentions using cURL. Ensure you replace $MENTIONSAPI_KEY with your actual API key.

```bash
curl "https://api.mentionsapi.com/v1/mentions/search?brand=Supabase&provider=openai&limit=10" \
  -H "Authorization: Bearer $MENTIONSAPI_KEY"
```

--------------------------------

### Example Usage Response

Source: https://mentionsapi.com/docs/endpoints/usage

This is an example of the JSON response you can expect when querying usage data. It includes details about the request, the usage window, and aggregated or series-based usage metrics.

```json
{
  "request_id": "9c0f…",
  "account_id": "c41a…",
  "plan": "growth",
  "window": {
    "start": "2026-04-01T00:00:00.000Z",
    "end":   "2026-04-25T00:00:00.000Z",
    "granularity": "day"
  },
  "total": {
    "requests": 2412,
    "billable_units": 3104,
    "cache_hits": 842,
    "errors": 7,
    "provider_breakdown": { "openai": 1570, "anthropic": 1412, "gemini": 122 }
  },
  "series": [
    { "bucket": "2026-04-01", "requests": 78, "billable_units": 102, "cache_hits": 12, "errors": 0, "provider_breakdown": { "openai": 66, "anthropic": 36 } },
    { "bucket": "2026-04-02", "requests": 102, "billable_units": 131, "cache_hits": 21, "errors": 1, "provider_breakdown": { "openai": 81, "anthropic": 50 } }
  ],
  "monthly_quota": 7500
}
```

--------------------------------

### Example Response from ChatGPT Live Mode

Source: https://mentionsapi.com/docs/api/check/mode-chatgpt-live

This JSON object shows a typical response when using the chatgpt_live mode. It includes details about mentioned brands, fan-out queries, and citations.

```json
{
  "id": "chk_a8d2c...",
  "mode": "chatgpt_live",
  "providers": {
    "chatgpt": {
      "mentioned": true,
      "rank": 6,
      "context": "Among the top picks for small businesses, HubSpot CRM stands out for its free tier and strong marketing automation...",
      "citations": [
        { "url": "https://www.g2.com/categories/crm", "title": "G2 CRM Reviews" },
        { "url": "https://blog.hubspot.com/sales/crm-software", "title": "HubSpot CRM Software Guide" }
      ],
      "fan_out": [
        "best free CRM 2026",
        "HubSpot vs Salesforce small business",
        "CRM features startups need",
        "free CRM with marketing automation"
      ],
      "brand_entities": [
        { "name": "HubSpot", "domain": "hubspot.com", "description": "Free CRM with marketing/sales suite" },
        { "name": "Salesforce", "domain": "salesforce.com" },
        { "name": "Zoho CRM", "domain": "zoho.com" },
        { "name": "Pipedrive", "domain": "pipedrive.com" }
      ]
    }
  },
  "duration_ms": 22418,
  "cost_cents": 10,
  "cache_hit": false
}
```

--------------------------------

### Example Ask API Request

Source: https://mentionsapi.com/docs/endpoints/ask

Demonstrates how to make a request to the Ask API endpoint using cURL. It specifies providers, a prompt, brands to track, and enables web search and caching.

```bash
curl https://api.mentionsapi.com/v1/ask \
  -H "Authorization: Bearer $MENTIONSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": ["openai", "anthropic", "perplexity"],
    "prompt": "Best PostgreSQL hosting providers in 2026?",
    "track_brands": ["Supabase", "Neon", "Render"],
    "web_search": true,
    "cache_scope": "shared"
  }'
```

--------------------------------

### Example cURL Request to MentionsAPI

Source: https://mentionsapi.com/docs/errors

This cURL command demonstrates how to make a request to the MentionsAPI, including necessary headers for authorization and content type.

```bash
curl -i https://api.mentionsapi.com/v1/ask \
  -H "Authorization: Bearer lvk_live_deadbeef" \
  -H "Content-Type: application/json" \
  -d '{}'
```

--------------------------------

### AI Overview Mode Response Example

Source: https://mentionsapi.com/docs/api/check/mode-ai-overview

This JSON structure represents a successful response from the AI Overview mode, including whether the brand was mentioned, its rank, context, and cited URLs.

```json
{
  "id": "chk_a8d2c...",
  "mode": "ai_overview",
  "providers": {
    "ai_overview": {
      "mentioned": true, "rank": 3,
      "context": "...HubSpot offers a free CRM with strong marketing automation features and is often recommended for small businesses...",
      "citations": [
        { "url": "https://www.hubspot.com/crm", "title": "HubSpot — hubspot.com" },
        { "url": "https://blog.hubspot.com/sales/free-crm-software", "title": "Free CRM Software" },
        { "url": "https://www.softwareadvice.com/crm/", "title": "Software Advice — CRM" }
      ],
      "fan_out": [],
      "brand_entities": []
    }
  },
  "duration_ms": 3402,
  "cost_cents": 5,
  "cache_hit": false
}
```

--------------------------------

### Perform On-Demand Brand Crawl

Source: https://mentionsapi.com/docs/endpoints/mentions

This example shows how to make a POST request to the /v1/mentions/crawl endpoint to initiate a brand crawl. It includes the required 'brand' field and an optional 'category' field.

```bash
curl https://api.mentionsapi.com/v1/mentions/crawl \
  -H "Authorization: Bearer $MENTIONSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Supabase",
    "category": "postgres-hosting"
  }'
```

--------------------------------

### POST /v1/ask

Source: https://mentionsapi.com/docs/endpoints/ask

Send a prompt to multiple LLM providers and get a consolidated response. This endpoint supports specifying providers, enabling web search, and tracking specific brands.

```APIDOC
## POST /v1/ask

### Description
Send a prompt to multiple LLM providers and get a consolidated response. This endpoint supports specifying providers, enabling web search, and tracking specific brands.

### Method
POST

### Endpoint
/v1/ask

### Parameters
#### Request Body
- **providers** (string[]) - Required - A list of LLM providers to query (e.g., "openai", "anthropic").
- **prompt** (string) - Required - The user's query.
- **track_brands** (string[]) - Optional - A list of brands to track mentions for.
- **web_search** (boolean) - Optional - Whether to perform web search as part of the query. Defaults to false.
- **cache_scope** (string) - Optional - The scope for caching results. Possible values: "shared".

### Request Example
```json
{
  "providers": ["openai", "anthropic", "perplexity"],
  "prompt": "Best PostgreSQL hosting providers in 2026?",
  "track_brands": ["Supabase", "Neon", "Render"],
  "web_search": true,
  "cache_scope": "shared"
}
```

### Response
#### Success Response (200)
- **request_id** (string) - Unique UUID for this call. Also echoed inside the archived payload as "id". Include in support tickets.
- **id** (string) - Same value as request_id. Use this to retrieve the response later via GET /v1/ask/:id (30-day retention).
- **cached** (boolean) - True if the response was served from cache. False for a fresh fan-out.
- **cache_tier** (string) - Which cache layer served the call ('l1', 'l2', 'l3', 'miss').
- **providers** (array) - One entry per provider in the order you requested. Successful entries have content + citations + tokens; failed entries have { provider, error: { code, message } }.
- **brand_mentions** (array) - Rolled-up extractions across all successful providers. Present whenever track_brands is set or defaults run.
- **citations** (array) - Deduplicated canonical citations across providers. Each entry aggregates the providers_cited that referenced it.
- **usage** (object) - Billing + latency info. { billable_units, latency_ms, cost_cents }.

### Response Example
```json
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "cached": false,
  "cache_tier": "miss",
  "providers": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "content": "...",
      "citations": [...],
      "tokens": {"input": 100, "output": 200},
      "latency_ms": 1500
    }
  ],
  "brand_mentions": [
    {
      "brand": "Supabase",
      "provider": "openai",
      "rank": 1,
      "sentiment": "positive",
      "context": "Supabase is a great option..."
    }
  ],
  "citations": [
    {
      "canonical_url": "https://supabase.com/docs",
      "domains": ["supabase.com"],
      "providers_cited": ["openai"],
      "title": "Supabase Docs"
    }
  ],
  "usage": {
    "billable_units": 1,
    "latency_ms": 1600,
    "cost_cents": 5
  }
}
```
```

--------------------------------

### Bing Copilot Mode Response Example

Source: https://mentionsapi.com/docs/api/check/mode-bing-copilot

This JSON response shows the structure when Bing Copilot mode is used. It includes whether the brand was mentioned, its rank, context, and citations.

```json
{
  "id": "chk_a8d2c...",
  "mode": "bing_copilot",
  "providers": {
    "bing_copilot": {
      "mentioned": true, "rank": 4,
      "context": "Top picks include HubSpot CRM (free tier with marketing tooling), Salesforce, Zoho, and Pipedrive...",
      "citations": [
        { "url": "https://www.hubspot.com/crm", "title": "HubSpot CRM" },
        { "url": "https://www.salesforce.com/", "title": "Salesforce" },
        { "url": "https://www.g2.com/categories/crm", "title": "G2 CRM Reviews" }
      ],
      "fan_out": [],
      "brand_entities": []
    }
  },
  "duration_ms": 3018,
  "cost_cents": 5,
  "cache_hit": false
}
```

--------------------------------

### Succeeded Ask Response

Source: https://mentionsapi.com/docs/endpoints/ask-retrieve

Example of a successful response from the GET /v1/ask/{id} endpoint. This includes detailed content, citations, brand mentions, and usage information.

```json
{
  "request_id": "req_01H8X2Y3Z4ABC",
  "id": "ask_01H8X2Y3Z4PQR5STU6VW7XYZ8",
  "cached": false,
  "cache_tier": "miss",
  "providers": [
    {
      "provider": "openai",
      "model": "gpt-4o-2024-11-20",
      "content": "Supabase has emerged as a developer favorite…",
      "latency_ms": 1240,
      "tokens": { "input": 64, "output": 312 },
      "citations": [
        { "url": "https://supabase.com/pricing", "domain": "supabase.com", "title": "Pricing | Supabase" }
      ]
    }
  ],
  "brand_mentions": [
    { "brand": "Supabase", "provider": "openai", "rank": 0, "sentiment": "positive", "context": "Supabase has emerged…" }
  ],
  "citations": [
    { "url": "https://supabase.com/pricing", "domain": "supabase.com", "title": "Pricing | Supabase" }
  ],
  "usage": {
    "billable_units": 1,
    "latency_ms": 1240,
    "cost_cents": 4
  }
}
```

--------------------------------

### POST /v1/ask

Source: https://mentionsapi.com/docs

Legacy endpoint for multi-LLM fan-out. New integrations should use /v1/check.

```APIDOC
## POST /v1/ask

### Description
This is a legacy endpoint for fanning out requests across multiple LLMs. It is recommended to use the `/v1/check` endpoint for new integrations.

### Method
POST

### Endpoint
/v1/ask

### Parameters
#### Request Body
- **prompt** (string) - Required - The prompt to send to the LLMs.
- **models** (array) - Optional - A list of LLM models to use.

### Request Example
```json
{
  "prompt": "What is the weather today?",
  "models": ["gpt-3.5-turbo", "claude-2"]
}
```

### Response
#### Success Response (200)
- **results** (object) - An object containing the responses from each LLM.

#### Response Example
```json
{
  "results": {
    "gpt-3.5-turbo": "The weather today is sunny.",
    "claude-2": "It is currently sunny with a high of 75 degrees Fahrenheit."
  }
}
```
```

--------------------------------

### Brand Extraction Request Example

Source: https://mentionsapi.com/docs/brand-extraction

Example JSON payload for a /v1/ask call to track specific brands. Ensure brand names are within the specified length limits.

```json
{
  "providers": ["openai"],
  "prompt": "Best CRM tools in 2026?",
  "track_brands": ["Salesforce", "HubSpot"]
}
```

--------------------------------

### AI Mode Response Example

Source: https://mentionsapi.com/docs/api/check/mode-ai-mode

This is an example of a successful response from the MentionsAPI when querying Google's AI Mode. It includes whether the brand was mentioned, its rank, context, and citations.

```json
{
  "id": "chk_a8d2c...",
  "mode": "ai_mode",
  "providers": {
    "ai_mode": {
      "mentioned": true, "rank": 2,
      "context": "**HubSpot CRM** offers a generous free tier — strong choice for small teams that want marketing automation without paying upfront...",
      "citations": [
        { "url": "https://www.hubspot.com/products/crm", "title": "HubSpot Products" },
        { "url": "https://blog.hubspot.com/sales/best-crm", "title": "Best CRM" }
      ],
      "fan_out": [],
      "brand_entities": []
    }
  },
  "duration_ms": 5803,
  "cost_cents": 10,
  "cache_hit": false
}
```

--------------------------------

### Make an 'all_live' mode API Call

Source: https://mentionsapi.com/docs/api/check/mode-all-live

Use this snippet to query six live AI search surfaces in parallel. Ensure you include the 'Authorization' and 'Content-Type' headers, and provide the 'mode', 'query', and 'brand' in the JSON payload.

```bash
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "all_live",
    "query": "best CRM for small business",
    "brand": "HubSpot"
  }'
```

--------------------------------

### GET /v1/usage

Source: https://mentionsapi.com/docs

Aggregates your API usage events for any specified time window. No authentication required.

```APIDOC
## GET /v1/usage

### Description
Fetches aggregated usage data for your account within a specified time range.

### Method
GET

### Endpoint
/v1/usage

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - The start of the time window (YYYY-MM-DD).
- **end_date** (string) - Optional - The end of the time window (YYYY-MM-DD).

### Response
#### Success Response (200)
- **total_calls** (integer) - The total number of API calls made.
- **total_cost** (number) - The total cost incurred.

#### Response Example
```json
{
  "total_calls": 1500,
  "total_cost": 75.50
}
```
```

--------------------------------

### Response - ai_overview mode

Source: https://mentionsapi.com/docs/api/check

This is a successful response for the 'ai_overview' mode, detailing mentions, context, and citations.

```APIDOC
## Response - ai_overview mode

### Description
This is a successful response for the 'ai_overview' mode, detailing mentions, context, and citations.

### Response Body
```json
{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "ai_overview",
  "providers": {
    "ai_overview": {
      "mentioned": true, "rank": 3,
      "context": "...HubSpot offers a free CRM with strong marketing automation features...",
      "citations": [
        { "url": "https://www.hubspot.com/crm", "title": "HubSpot — hubspot.com" },
        { "url": "https://blog.hubspot.com/sales/free-crm-software", "title": "Free CRM Software" }
      ],
      "fan_out": [],
      "brand_entities": []
    }
  },
  "cost_cents": 5,
  "duration_ms": 3402,
  "cache_hit": false
}
```
```

--------------------------------

### Account usage rollup with curl

Source: https://mentionsapi.com/docs/sdks/curl

Use this endpoint to get an account usage rollup. It accepts a granularity parameter.

```bash
curl https://api.mentionsapi.com/v1/usage?granularity=total \
  -H "Authorization: Bearer lvk_live_..."
```

--------------------------------

### Webhook Signature Headers

Source: https://mentionsapi.com/docs/webhooks

Example HTTP headers for webhook verification, including the primary signature and legacy timestamped signature.

```http
x-mentionsapi-signature: 5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
x-mentionsapi-timestamp: 1714117284
x-mentionsapi-event: ask.completed
x-mentionsapi-delivery-id: 7b8e6a3c-...
x-mentions-signature: t=1714117284,v1=8d1f0c2b9e...
Content-Type: application/json
```

--------------------------------

### TypeScript SDK: Ask and Retrieve Results

Source: https://mentionsapi.com/docs/endpoints/ask-retrieve

This TypeScript example demonstrates how to use the SDK to initiate an ask request in standard mode and then poll for the results. It includes a helper function to poll until the status is 'succeeded' or 'failed'.

```typescript
import { MentionsAPIClient } from "@mentionsapi/sdk";

const client = new MentionsAPIClient({ apiKey: process.env.MENTIONSAPI_KEY! });

// Fire a standard-mode (async, 30% cheaper) ask
const queued = await client.ask({
  prompt: "Best PostgreSQL hosting providers in 2026?",
  providers: ["openai", "anthropic", "perplexity"],
  mode: "standard",
});

// Poll until it completes
async function poll(id: string) {
  while (true) {
    const res = await client.askRetrieve(id);
    if (res.status === "succeeded" || res.status === undefined) return res;
    if (res.status === "failed") throw new Error(res.error?.message ?? "failed");
    await new Promise((r) => setTimeout(r, 5_000));
  }
}

const result = await poll(queued.ask_id ?? queued.id);
console.log(result.providers);
```

--------------------------------

### Get Monitor by ID

Source: https://mentionsapi.com/docs/endpoints/monitors

Fetches a specific monitor by its ID, including its 10 most recent runs. Requires session authentication.

```APIDOC
## GET /v1/monitors/:id

### Description
Fetches a specific monitor by its ID and its 10 most recent runs. This endpoint is session-authenticated.

### Method
GET

### Endpoint
/v1/monitors/:id

### Parameters
#### Path Parameters
- **id** (string) - Required. The unique identifier of the monitor.

### Response
#### Success Response (200)
- **request_id** (string) - Unique identifier for the request.
- **monitor** (object) - The Monitor object.
- **runs** (array) - An array of the 10 most recent runs for the monitor.

### Response Example
```json
{
  "request_id": "…",
  "monitor": {
    "id": "…",
    "account_id": "…",
    "name": "My Daily Monitor",
    "prompt": "Summarize the latest news about AI.",
    "providers": ["openai", "anthropic"],
    "cadence": "daily",
    "track_brands": ["OpenAI", "Anthropic"],
    "webhook_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "enabled": true,
    "next_run_at": "2026-04-26T08:00:00.000Z",
    "last_run_at": "2026-04-25T08:00:00.000Z",
    "created_at": "2026-04-24T10:00:00.000Z",
    "updated_at": "2026-04-24T10:00:00.000Z"
  },
  "runs": [
    {
      "id": "…",
      "monitor_id": "…",
      "ran_at": "2026-04-25T08:00:00.000Z",
      "status": "succeeded",
      "diff_summary": "2 new mentions vs previous run",
      "response": { /* NormalizedResponse */ },
      "cost_cents": 75
    }
  ]
}
```
```

--------------------------------

### Configure MentionsAPI MCP Server

Source: https://mentionsapi.com/docs/mcp/cursor

Add the mentionsapi MCP server to your Cursor project by creating or editing the `.cursor/mcp.json` file. This configuration specifies the command to run, arguments, and environment variables, including your API key.

```json
// .cursor/mcp.json (project-scoped) — or ~/.cursor/mcp.json (global)
{
  "mcpServers": {
    "mentionsapi": {
      "command": "npx",
      "args": ["-y", "@mentionsapi/mcp@latest"],
      "env": {
        "MENTIONSAPI_API_KEY": "lvk_live_..."
      }
    }
  }
}
```

--------------------------------

### Delete (Pause) Watch

Source: https://mentionsapi.com/docs/api/watch

Soft-deletes (pauses) a watch. The watch record is preserved, and subsequent GET requests will return a 'paused' status.

```APIDOC
## Delete (pause) a watch — DELETE /v1/watch/{id}

### Description
Soft-deletes (pauses) a watch. The watch record and its historical runs are preserved.

### Method
DELETE

### Endpoint
/v1/watch/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the watch to pause.

### Response
#### Success Response (200)
DELETE is a soft-pause: the watch is set to `enabled=false` but the record (and its historical runs) are preserved. A subsequent GET returns `status: 'paused'` rather than 404. There is currently no hard-delete; if you need permanent deletion, email support@mentionsapi.com.

### Request Example
```bash
curl -X DELETE https://api.mentionsapi.com/v1/watch/f3e8c7d2-ப்புகளை... \
  -H "Authorization: Bearer lvk_live_..."
```
```

--------------------------------

### Sample Output of Brand Mentions Across Surfaces

Source: https://mentionsapi.com/docs/recipes/track-brands-across-platforms

This is a sample of the JSON output you can expect when tracking a brand across multiple AI search surfaces. It details whether the brand was mentioned, its rank, and the number of citations for each surface.

```bash
--- best CRM for startups ---
{ surface: 'perplexity',   mentioned: true,  rank: 6,    citations: 10 }
{ surface: 'chatgpt',      mentioned: true,  rank: 4,    citations: 4  }
{ surface: 'gemini',       mentioned: true,  rank: 5,    citations: 6  }
{ surface: 'ai_overview',  mentioned: true,  rank: 3,    citations: 8  }
{ surface: 'ai_mode',      mentioned: true,  rank: 2,    citations: 5  }
{ surface: 'bing_copilot', mentioned: false, rank: null, citations: 7  }
```

--------------------------------

### GET /v1/webhooks

Source: https://mentionsapi.com/docs/endpoints/webhooks

Lists all webhook endpoints configured for the calling account. It returns a list of webhook objects, each containing details about a registered endpoint.

```APIDOC
## GET /v1/webhooks

### Description
Lists all webhook endpoints for the calling account.

### Method
GET

### Endpoint
/v1/webhooks

### Response
#### Success Response (200)
- **webhooks** (array) - A list of webhook objects.
  - **id** (string) - Endpoint identifier.
  - **url** (string) - Target URL.
  - **description** (string | null) - Optional label.
  - **events** (array) - Subscribed events (e.g., ['ask.completed']).
  - **enabled** (boolean) - Indicates if the endpoint is enabled.
  - **created_at** (string) - Timestamp of creation.

### Response Example
```json
{
  "request_id": "…",
  "webhooks": [
    {
      "id": "…",
      "url": "https://example.com/hooks/mentionsapi",
      "description": "Prod ingestion",
      "events": ["ask.completed"],
      "enabled": true,
      "created_at": "2026-04-10T11:04:00.000Z"
    }
  ]
}
```
```

--------------------------------

### API Check Response Example (mode:quick)

Source: https://mentionsapi.com/docs/api/check

This JSON object represents a successful response from the API's check endpoint when using the 'quick' mode. It includes details about the query, brand, and the results from each LLM provider, such as mention status, rank, context, and citations.

```json
{
  "request_id": "req_01JBQ2K8H...",
  "id": "chk_a8d2c...",
  "mode": "quick",
  "query": "best CRM for small business",
  "brand": "HubSpot",
  "providers": {
    "chatgpt": { "mentioned": true, "rank": 6, "context": "Top picks include HubSpot CRM...", "citations": [], "fan_out": [] },
    "claude":  { "mentioned": true, "rank": 4, "context": "...", "citations": [{"url":"https://www.hubspot.com/crm","title":"hubspot.com"}], "fan_out": [] },
    "gemini":  { "mentioned": true, "rank": 7, "context": "...", "citations": [], "fan_out": [] },
    "perplexity": { "mentioned": true, "rank": 6, "context": "...", "citations": [{"url":"https://zapier.com/blog/best-crms/","title":"Zapier"}], "fan_out": [] }
  },
  "created_at": "2026-04-25T12:00:00Z",
  "duration_ms": 4218,
  "cost_cents": 39,
  "balance_after_cents": 9961,
  "cache_hit": false
}
```

--------------------------------

### Example MentionsAPI Error Response

Source: https://mentionsapi.com/docs/errors

This HTTP response shows the standard JSON shape for MentionsAPI errors, including an `error.code`, `error.message`, and a `request_id` for support.

```http
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "unauthorized",
    "message": "API key not found."
  },
  "request_id": "req_01H8X2Y3Z4PQR5STU6VW7XYZ8"
}
```

--------------------------------

### GET /v1/health

Source: https://mentionsapi.com/docs

Provides a public snapshot of the API's reliability, including a 7-day rolling success rate and p95 latency. No authentication required.

```APIDOC
## GET /v1/health

### Description
Retrieves a public overview of the API's operational health, including historical performance metrics.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **success_rate_7d** (number) - The success rate over the past 7 days.
- **p95_latency_7d** (number) - The 95th percentile latency over the past 7 days.

#### Response Example
```json
{
  "success_rate_7d": 0.995,
  "p95_latency_7d": 150
}
```
```

--------------------------------

### Import OpenAPI Spec into Bruno and Hoppscotch

Source: https://mentionsapi.com/docs/openapi

Instructions for importing the OpenAPI v3 specification directly into API clients like Bruno and Hoppscotch. Bruno stores requests as files, while Hoppscotch runs in the browser.

```bash
# Bruno
File -> Import Collection -> OpenAPI v3 spec
Paste: https://mentionsapi.com/openapi.json

# Hoppscotch
Settings -> Import / Export -> Import from OpenAPI
Paste: https://mentionsapi.com/openapi.json
```

--------------------------------

### Delete (Pause) a Watch

Source: https://mentionsapi.com/docs/api/watch

This cURL command soft-deletes (pauses) a watch. The watch record and its history are preserved, and a subsequent GET request will return a 'paused' status.

```bash
curl -X DELETE https://api.mentionsapi.com/v1/watch/f3e8c7d2-ப்புகளை... \
  -H "Authorization: Bearer lvk_live_..."
```