API Documentation

API: LLMPulse

Build dashboards, ETL pipelines and automations with a clean, well-typed API.

LLM Pulse is an AI visibility analytics platform that monitors how your brand appears in AI-generated responses from ChatGPT, Perplexity, Gemini, and other LLMs. The API gives you programmatic access to all your visibility data, including brand mentions, citation sources, sentiment analysis, and share of voice metrics. Use it to build custom dashboards, automate reports, or integrate AI visibility tracking into your existing tools.

Quick start

The logical flow is: list resources → (optionally) fetch dimensions → query metrics. The first call to /dimensions/projects already validates your API key.

1. List your projects: GET /dimensions/projects
2. (Optional) Fetch project dimensions (competitors, models, locales, tags)
3. Request metrics under /metrics/*

Official CLI & SDKs

Use the native CLI from a terminal or add a typed SDK to your application. Both cover all 71 documented REST operations and work with the same API keys and base URL shown in this reference.

API Playground

curl -X GET "https://api.llmpulse.ai/api/v1/ping" -H "Authorization: Bearer YOUR_API_KEY"

Response will appear here...

Authentication

Send your key in the Authorization header as a Bearer token. Rotate/revoke under Settings → API Keys.

Missing or malformed headers return 401 ERR_MISSING_AUTH. Unknown keys return 401 ERR_INVALID_API_KEY. Revoked keys return 403 ERR_REVOKED_API_KEY.

Each call runs in the context of the API key’s user. Projects must belong to that user; otherwise 404 ERR_PROJECT_NOT_FOUND.

Versioning & Rate limits

Current version: v1. Future breaking changes will bump the path (e.g. /api/v2).

Rate limiting: 300 requests per minute per API key. Contact us for higher quotas.

Metrics endpoints support conditional GET (ETag/Last-Modified); see Cache & Conditional GET.

Dimensions endpoints

GET/dimensions/projects

Lists the authenticated user’s projects (this is also an auth check).

GET/dimensions/competitors

Lists competitors for the project.

GET/dimensions/collections

Lists collections (Tags) belonging to the project.

GET/dimensions/tags

Alias for /dimensions/collections. Returns the same payload, but named as tags for consistency with the UI.

GET/dimensions/models

Lists models present in daily metrics for the project.

GET/dimensions/locales

Lists countries and languages present in daily metrics for the project.

GET/dimensions/sentiments

(Optional) Lists available sentiment buckets and their metric names.

GET/dimensions/prompts

Lists prompts in a project.

GET/dimensions/prompt_executions

Lists prompt executions in a project.

GET/dimensions/sources

Lists non-rejected sources produced by prompt executions.

GET/dimensions/mentions

Lists mentions created by your project.

GET/dimensions/citations

Lists citations created by your project.

GET/dimensions/competitor_mentions

Lists competitor mentions detected in your executions.

GET/dimensions/competitor_citations

Lists competitor citations detected in your executions.

GET/dimensions/all_mentions

Unified endpoint combining brand and competitor mentions. Each record includes an actor_type field (project or competitor).

GET/dimensions/all_citations

Unified endpoint combining brand and competitor citations. Each record includes an actor_type field (project or competitor).

GET/dimensions/projects/:id

Get detailed information about a project: matching names, industry, business model, prompt counts per brand focus, and data_coverage (the models, countries and languages that actually have data), so one call replaces separate models/locales lookups.

GET/dimensions/competitors/:id

Get detailed information about a competitor including matching names and app store IDs.

Agent Analytics

Surfaces AI bot crawler traffic hitting your origin server (GPTBot, PerplexityBot, ClaudeBot, OAI-SearchBot, Google-Extended, and ~25 other AI bots) from Cloudflare or CSV uploads. Available on Scale and above.

GET/metrics/agent_traffic

Aggregated AI bot traffic for a project, grouped by bot or by company, with daily/weekly/monthly granularity.

GET/dimensions/agent_bots

Static catalog of AI bots that Agent Analytics can identify. Use it to render filter UIs that mirror our internal classification (slug, display name, company, category, Cloudflare verified-bot mapping). Requires Scale or above; the MCP tool list_agent_bots is available on every plan.

Search Console

Google Search Console performance data (impressions, clicks, CTR, average position) for projects with a connected GSC property. Growth plan or above required. ctr is a 0..1 fraction and position is the impression-weighted average, matching the Search Console API. Projects without a connected property return ERR_SEARCH_CONSOLE_NOT_CONNECTED (404).

GET/search_console/summary

Property-wide headline totals for the range, with an optional country or device breakdown aggregated over the same range.

GET/search_console/timeseries

Property-wide series bucketed by day, week or month.

GET/search_console/queries

Top search queries for the range, ranked and paginated. Knowingly undercounts anonymized queries, so they do not sum exactly to the summary totals (same as the GSC UI).

GET/search_console/pages

Top landing pages for the range, ranked and paginated. Same shape as the queries endpoint, with each row key being a page URL.

Citation Intelligence

Cited-page intelligence, grouped URL/domain/host views, page-cache metadata, mention evidence inside cited pages, occurrence lists, and sanitized cached content.

GET/citation_intelligence/groups

Grouped citation intelligence by url, domain, or host with per-model breakdown, citation rate, and average citation position (ignores position = 0 rows).

GET/citation_intelligence/mentions_by_domain

For the responses where each given source domain is cited, the share of those responses that mention your brand vs each competitor. Brand and competitors are normalized to sum to 100% per domain, mirroring the Share of Voice mention definition. Pass several domains to analyze the whole matrix in one call.

GET/citation_intelligence/urls/:url_sha256

URL-level detail for one cited page: totals, citation rate, avg citation position, source-type counts, per-model counts, distinct URL variants, page-cache metadata, and page mention evidence with snippets and actor labels.

• Params: project_id (required), :url_sha256 (64 hex chars in URL), same optional filters as /citation_intelligence/groups. ERR_NOT_FOUND only when the URL was never cited by the project; filters that empty the result still return 200 with zero stats.

GET/citation_intelligence/urls/:url_sha256/occurrences

Paginated occurrences of a cited URL across prompt executions, with response excerpt, prompt text, model, executed_at, citation_position and source_type per row.

• Params: project_id (required), :url_sha256 (64 hex chars), page, per_page, same optional filters as /citation_intelligence/groups.

GET/citation_intelligence/urls/:url_sha256/content

Sanitized cached page content for a cited URL: page-cache metadata, mention evidence and snippets, full plain text, and rendered HTML (scripts and unsafe markup removed).

AI Model Insights

Aggregate parts of the in-app AI Model Insights report. All three endpoints filter by executed_at (not created_at) and share a standard actor shape: { type, id, competitor_id, name, domain } with bare (scheme-less) domains.

GET/reports/ai_model_insights/summary

Per-model mention counts and shares, citation counts and shares, brand net sentiment with raw positive/negative counts, weighted visibility totals and shares, plus actor matrices for each.

GET/reports/ai_model_insights/position_distribution

Position-distribution comparison used in the AI Model Insights report: one or two brand series with bucketed totals (Position 1, Position 2-3, Position 4-7, Position 8+) and chart-ready time series per bucket.

GET/reports/ai_model_insights/ai_overview_results

Aggregate Google AI Overview result-availability data: total AI Overview responses, responses with results (no_result = false), result rate, chart-ready trend data, and a paginated by-prompt result-rate table.

Recommendations

Read-only API for the same recommendation runs that power the in-app Recommendations experience.

GET/recommendations

Lists recommendation runs for a project with type/status filters.

GET/recommendations/:id

One recommendation run with its items and report data: items array with title, priority, action steps, metadata, source references, plus item counts grouped by active, completed, archived.

POST/recommendations

Launch a new generation (same engine as the in-app Recommendations page). Runs async (1-3 minutes); poll GET /recommendations/:id until status is completed. Consumes the project weekly recommendation-item budget (ERR_LIMIT_REACHED when exhausted, or when a run of the same type is already pending). sentiment_reputation requires Scale or above. Requires a writable API key.

Answers (AI Responses)

Access the actual AI-generated responses with full content, mentions, citations, and sentiment analysis.

GET/answers

List AI responses with their content. Returns paginated results with truncated response text (max 10,000 chars). Pass query for case-insensitive full-text search inside response texts: total becomes the exact count of matching responses, and each item returns snippet and match_count instead of the full response.

GET/answers/:id

Get a single AI response with full details including mentions, citations, sentiments, and sources.

Detailed Sentiments

Access detailed sentiment analysis with comments, topics, and scores. This is different from /dimensions/sentiments which only returns sentiment categories.

GET/sentiments

List detailed sentiment records with full analysis context.

Prompts (Bulk Create + Delete)

Add prompts to a project in bulk via the API. Validates against account prompt limits and deduplicates automatically.

POST/prompts

Create up to 100 prompts per request. Existing prompts (same text + locale) are skipped.

DELETE/prompts/:id

Delete a prompt. Irreversible; the prompt disappears immediately, frees a prompt slot, and its history (executions, mentions, citations, sentiment) is purged by a background job. Requires a writable API key.

GEO Writer

Create and manage AI-powered GEO Writer tasks via the API. Tasks are processed asynchronously and results can be polled.

POST/intelligence_tasks

Create a GEO Writer task. Two modes: prompt-based (provide prompt_id) or agentic (provide custom_topic and/or user_instructions).

GET/intelligence_tasks

List GEO Writer tasks for a project with optional filtering.

GET/intelligence_tasks/:id

Get full task details including result data when completed. Accepts numeric ID or public_id.

Agent Write Endpoints

These endpoints accept POST/PATCH/PUT/DELETE and require an API key with the read_write scope. A token with the read scope receives 403 ERR_INSUFFICIENT_SCOPE. Writes share a tighter rate limit (60/min/key) in addition to the global 300/min/key budget.

POST/projects

Create a complete project in one call (fast mode): project, prompts (queued for execution + categorization), competitors, weekly email subscription. Idempotent when external_identifier is provided. The project always belongs to the account owner.

• Body (JSON): website_url (required public HTTP(S) URL with a DNS hostname or public IP address; credentials, private and special IP addresses, localhost and internal hostnames are rejected), name (required), main_country (required), main_language (required), brand_name, description, industry (array), matching_names (array), prompts (array, max 100), competitors (array of {domain, brand_name, matching_names}), owned_media (object, Growth+), use_subdomain, weekly_email_subscribed, external_identifier (embed-enabled accounts only; idempotency key, [a-z0-9_-]{1,64}), execute_prompts_immediately (default true).

Project Drafts wizard

Multi-step project wizard with AI suggestions: POST /project_drafts starts a draft (returns suggested name/description/industry for the URL), PATCH submits each step (details, prompts, competitors, owned_media) with strict forward gating and returns suggestions for the next step, POST /project_drafts/:id/finalize creates the real project. Drafts expire after 24h.

• The initial website_url must be a public HTTP(S) URL with a DNS hostname or public IP address. Credentials, private and special IP addresses, localhost and internal hostnames are rejected. Steps: details (name required), prompts (max 100, quota-validated), competitors (plan-capped), owned_media (optional, Growth+). Suggestions per step with suggest=false opt-out; cold URLs can take up to ~2 minutes, set client timeout to 180s. Finalize is idempotent and re-validates every gate.

POST/competitors

Add a competitor (brand_name + domain) to a project. Honours the per-plan max competitors cap.

PATCH/DELETE /competitors/:id

Update a competitor (brand_name, matching_names, color; the domain is immutable after creation) or delete it. Name changes re-run mention/citation matching in the background (processing: true for a few minutes, edits blocked meanwhile). Deleting is irreversible and purges the competitor data in the background.

POST/collections

Create a tag (Collection) in a project. Optionally attach existing prompts in the same call. Tag name is case-insensitive unique per project.

PATCH/DELETE /collections/:id

Rename a tag or change its description, or delete it. Deleting a tag keeps the prompts inside it; only the grouping disappears. Prompt membership is managed via POST /prompts/assign_tags.

• PATCH body: project_id (required), name and/or description. DELETE: project_id + :id in URL.

POST/prompts/assign_tags

Idempotent bulk attachment of tags to existing prompts. Tags can be resolved by id or name.

POST/annotations

Mark a date in the project timeseries with a title + description. Available on every plan.

GET /annotations + PATCH/DELETE /annotations/:id

List, update, and delete annotations on every plan. GET returns manual, automatic, GEO test, and platform annotations newest first. The origin field distinguishes them, and editable says whether the requesting user may modify a row. PATCH and DELETE only work on manual annotations belonging to your own user (403 otherwise).

• GET query: project_id (required), from/to (YYYY-MM-DD), annotation_category_id, page, per_page. PATCH body: any of title, description, annotation_date, color, annotation_category_id. DELETE: project_id + :id in URL.

POST/technical_geo_reports

Launch the full technical GEO analysis bundle (crawlability, schema, content readiness, discoverability, site structure, robots.txt, llms.txt, AI visibility) for a URL + country. Each report runs as a background job.

Webhooks

Receive a signed HTTP POST every time something happens in a project, with no polling. Webhooks power the LLM Pulse connectors for Zapier, Make and n8n, and work with any custom backend. Available on the Scale plan and above. Each delivery is a JSON envelope: { "event", "occurred_at", "project_id", "subscription_id", "data" }.

• Event types: mention.created, competitor_mention.created, citation.created, prompt_execution.completed, sentiment.negative_detected (negative or very negative brand sentiment), recommendation.completed, intelligence_task.completed.
• Security: every delivery carries X-LLMPulse-Event, X-LLMPulse-Delivery (unique id) and X-LLMPulse-Signature (sha256=<hex>, HMAC-SHA256 of the raw body computed with the subscription secret). Verify the signature to authenticate deliveries.
• Delivery: a 2xx response acknowledges the event; anything else is retried 5 times with exponential backoff. Subscriptions auto-disable after 20 consecutive failed deliveries.

POST/webhooks

Create a subscription. Idempotent: re-posting the same project + event + URL returns the existing subscription. The signing secret (whsec_...) is only returned by this endpoint, store it to verify delivery signatures. Requires a read_write scope key.

GET/webhooks

List active subscriptions for the account. Items match the create response without the secret.

DELETE/webhooks/:id

Delete a subscription. The target URL stops receiving events immediately. Requires a read_write scope key.

GET/webhooks/sample/:event_type

Up to 3 example event payloads for the event type, built from the project''s most recent real data (or a static sample when the project has no data yet). Used by integration editors such as the Zapier sample loader. Also available as the MCP tool get_webhook_sample.

Filters & Common params

• project_id required for all project-scoped endpoints.
• metrics or metric: CSV of mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment
• granularity: day|week|month (weeks start Monday)
• Time window: either range (days) or from & to (ISO8601). If you send to, from is required. Defaults with from/to: missing from = 30 days ago (start of day); missing to = now (end of day).
• Filters: model, collection_id (tag id), prompt (prompt ID), country_code, language_code, competitors (CSV IDs)
• include_project (default true): set false to exclude your project (return only competitors).

Output Formats for BI Tools

Read endpoints return nested JSON by default, which is convenient for code but unreadable for business intelligence tools. Pass the optional output parameter to get the same data as a rectangular table that Tableau, Excel, Google Sheets or a warehouse loader can consume directly.

• output omitted (default): the nested JSON documented for each endpoint. Unchanged, so existing integrations are unaffected.
• output=flat: the same metadata plus columns (ordered column names), rows (one flat object per row) and row_count.
• output=csv: the same rows as text/csv, with columns as the header row.

Supported on /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources, the /search_console/* series and the list-returning /dimensions/* endpoints. Endpoints whose payload is not a single table (/metrics/agent_traffic, /metrics/ai_traffic, /search_console/summary, /dimensions/models, /dimensions/locales) reject output instead of ignoring it.

/metrics/sov also accepts view=over_time (default), view=current or view=breakdown: its payload holds several different shapes and a table can only hold one at a time.

Columns by endpoint

Example

GET /api/v1/metrics/timeseries?project_id=1&range=30&metrics=mentions&output=csv

date,actor_type,actor_id,actor_name,actor_domain,metric,value
2025-01-01,project,1,My Brand,mybrand.com,mentions,10
2025-01-01,competitor,2,Competitor A,competitor.com,mentions,5

Notes:

• Errors are always returned as JSON, never as CSV, so a failure is never mistaken for data.
• Percentages stay on the raw 0-100 scale, exactly as in the JSON response.
• Text cells that begin with an equals, plus, minus or at sign are escaped so spreadsheets do not execute them as formulas.
• Paginated endpoints also return their paging metadata in the X-Total-Count, X-Page and X-Per-Page response headers, which a CSV body cannot carry.
• Flat output is capped at 200,000 rows. Above that, narrow the date range, request fewer metrics, or use granularity=week.
• Endpoints without a flat projection reject output with ERR_INVALID_PARAM instead of ignoring it.

Metrics: Semantics & aggregation

These semantics are aligned 1:1 with the Overview UI.

• mentions: daily sums of mentions_count. For week/month we compute the PERIOD TOTAL (Mon-Sun for weeks) and repeat that same total for every day in the period. If a period’s total is 0, we “carry” the last non-zero period total (sticky).
• citations: response-level count that includes visible citations and background source references. Each actor counts at most once per response. Uses the same period-total and sticky-carry behavior as mentions.
• responses: total number of prompt executions (API calls to LLMs). Uses project-level execution count regardless of actor. • day: daily sum. • week/month: period total (no sticky carry, days with 0 executions show 0).
• Mention Rate mention_rate (also accepted as visibility): percentage per actor, using the project-level executions as denominator under the same filters (mentions_count / prompt_executions_count × 100). • day: compute the daily ratio. • week/month: compute the ratio-of-sums for the period (Σ mentions / Σ executions) and repeat that value for every day in the period. If the period's denominator is 0, carry forward the last non-null value.
• citation_rate: percentage of responses that include a visible or background citation for the actor (citations_count / prompt_executions_count × 100). • day: daily ratio. • week/month: ratio-of-period-sums with sticky carry, same as visibility.
• AI Visibility Score ai_visibility_score: position-weighted visibility metric that accounts for mention prominence. Uses reciprocal position weighting (position 1 = 100%, position 2 = 50%, position 3 = 33%, etc.). Higher scores indicate both more mentions AND better positioning. • day: compute daily weighted score / executions. • week/month: ratio-of-period-sums with sticky carry, same as visibility.
• avg_position: average visible citation position. Background citations have no visible position and are excluded. • day: daily average excluding nulls. • week/month: average within the period (ignoring nulls) and then propagate (carry) the last known value to days without data, matching the Overview chart smoothing.
• avg_mention_position: average position of the brand when mentioned in AI responses (position 1 = first mentioned, position 2 = second, etc.). Lower is better. • day: daily average excluding nulls. • week/month: average within the period with sticky carry.
• Sentiment metrics sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative: for each actor and day, percentage of sentiments in that bucket over all sentiments for that actor. • day: daily ratio (bucket_count / total_sentiments * 100). Days with no sentiments return null. • week/month: we compute a ratio-of-period-sums (Σ bucket / Σ total * 100) and repeat that percentage for every day in the period. If the period’s denominator is 0, we carry forward the last non-null value (sticky), matching the Overview smoothing.
• Net Sentiment Score net_sentiment: para cada actor y día, calculamos un score en [-100, 100]: ( (very_positive + positive) − (negative + very_negative) ) / total_sentiments × 100. • day: usamos los porcentajes diarios de cada bucket (las métricas sentiment_*) y calculamos net = (pos+very_pos) − (neg+very_neg). • week/month: el score hereda las mismas semánticas de agregación/smoothing que los buckets de sentiment, porque se calcula a partir de esas series.

In /metrics/summary, total is a sum for count metrics and an average for avg_position, avg_mention_position, and net_sentiment.

GET /metrics/timeseries

Returns time series for one or more metrics, grouped by actor (your project + selected competitors). Weekly/monthly values follow the period semantics above. Optional prompt_type (search intent) and brand_kind filters scope every metric to a prompt category.

GET /metrics/summary

Aggregates per actor and metric (total/min/max/last). Ideal for KPI tiles.

GET /metrics/prompt_summary

Returns paginated per-prompt aggregated metrics (responses, mentions, citations, mention_rate, citation_rate, avg_mention_position, avg_position). Supports breakdown=model to add the AI model dimension to each row, returning per-prompt per-model metrics. Params: sort (responses, mentions, citations, mention_rate or visibility, citation_rate, avg_mention_position, avg_position), sort_dir (asc/desc), breakdown (model), page, per_page (max 100).

GET /metrics/sov

Share of Voice based on mentions, aligned with Overview.

• over_time: for each date, SOV = (actor_mentions / sum_all_mentions) × 100. If the daily sum is 0, the last value is carried forward (sticky).
• current: uses the latest date with non-zero total; if none, it uses totals over the whole range.
• breakdown: top 4 actors + an aggregated Others row (and a detailed others list).

GET /metrics/top_sources

Ranks source domains by number of responses and average mention rate (% of executions that surfaced that domain).

• The dataset includes non-rejected sources linked to prompt executions within the window and current filters.
• total_responses: number of unique prompt executions that produced at least one source on that domain.
• avg_mention_rate (also returned as avg_visibility): (count of source rows for the domain / total executions) × 100.
• Sorting: sort=total_responses (default), sort=avg_mention_rate, or sort=avg_visibility.
• Pagination: page (>=1), per_page (default 20, max 100).
• Filter by domain: query (case-insensitive LIKE), e.g. query=github.

GET /metrics/ai_traffic

Returns the AI-referred traffic measured from a project's connected web analytics provider (Google Analytics 4, Adobe Analytics, PostHog, Plausible or Piano): per-day users, sessions and conversions grouped by AI source (ChatGPT, Perplexity, Gemini, Claude and others), with totals and a conversion rate. Requires the Scale plan or above and a connected provider; projects without one return ERR_AI_TRAFFIC_NOT_CONNECTED (404).

Cache & Conditional GET

Metrics endpoints (timeseries, summary, sov, top_sources) support conditional GET. We compute an ETag from the project version and a hash of your query params, and use the project’s updated_at as Last-Modified.

Send If-None-Match or If-Modified-Since to receive 304 Not Modified when nothing changed.

Errors

Errors are consistent and machine-parsable:

Error body shape:

Typical 422 cases:

• invalid metrics: only mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment are allowed.
• invalid granularity: must be day|week|month.
• from/to must be ISO8601, or from is required with to.
• range is required when neither from nor to are sent.
• unknown competitor ids: ...: IDs not found under the project.

Client snippets

Examples in multiple languages are shown in the code panel on the right.

Postman: Download & Environment

Use this curated Postman collection to explore the API quickly and securely. It mirrors the examples and metric semantics described above (period totals with sticky carry, ratio-of-period-sums for visibility, and propagation for avg_position), so you can validate responses and prototype integrations in minutes.

Download the collection

Download LLMPulse API v1 Postman Collection

Import the file in Postman (File → Import), then select or create the environment shown below. The collection uses variables, so you won’t need to edit each request manually.

Environment (placeholders, keep your IDs private)

Create a new Environment in Postman with the following variables. Use placeholders instead of real IDs or keys in any public context (docs, screenshots, etc.):

How it’s used:

• The collection reads {{base_url}} and injects Authorization: Bearer {{api_key}} automatically.
• Set {{project_id}} to a project you own; {{competitors}} is CSV (e.g. 1,2,3).
• You can override per request (e.g. send from/to instead of range) and add filters like model, collection_id, country_code, language_code.
• Keep your API key in your private environment only; do not paste it into shared documents.

MCP (AI Integration)

MCP (Model Context Protocol) allows AI assistants like ChatGPT, Claude and Gemini to access your LLM Pulse data directly. Available on every plan via OAuth, no API key required. Ask questions in natural language and let the AI fetch and analyze your visibility data.

What is MCP?

MCP is an open protocol that lets AI assistants connect to external data sources. Instead of copying data or making API calls manually, you can simply ask your AI assistant questions like "What's my visibility trend this month?" and it will fetch the data automatically.

Endpoint

Configuration

Recommended for every plan: paste the MCP URL into your AI client. The client handles OAuth automatically, no token to copy. API-key auth (Bearer header) is available on the Scale plan and above for headless integrations.

Struggling to connect?

MCP and OAuth support is still uneven across AI clients, so connections sometimes fail to establish. On the Scale plan and above, the easiest fallback is to give your AI assistant a Bearer API key plus a link to these API docs. It can then query every endpoint directly over plain HTTP, with no MCP client setup at all.

Available Tools

These tools are available to your AI assistant.

Live list rendered from Mcp::LlmPulseServer::TOOLS (74 tools registered). The MCP server filters tools/list per user plan.

Protocol

MCP uses JSON-RPC 2.0 over Streamable HTTP. Requests return a JSON-RPC response. Accepted notifications return HTTP 202 with an empty body.

For a simpler guide, see the MCP Setup page.

OAuth 2.1 (ChatGPT Apps SDK, MCP clients)

OAuth 2.1 authorization server with PKCE-S256, Dynamic Client Registration (RFC 7591), and discovery metadata (RFC 8414 + RFC 9728). Used by ChatGPT Apps SDK and any other MCP client that supports OAuth. Available to all plans for the MCP resource at /api/v1/mcp. RS256-signed JWT access tokens and the reusable refresh token share a fixed one-year authorization deadline.

OAuth 2.1 Overview

Use OAuth 2.1 when your client needs per-user delegated access to the MCP endpoint and you cannot ship an API key (e.g., a multi-tenant AI assistant). Use API keys when you control both ends and want a simpler integration (Scale plan and above). MCP via OAuth is available on every plan including the free trial.

Endpoints: /oauth/authorize, /oauth/token, /oauth/register, /oauth/jwks.json, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource.

GET/.well-known/oauth-authorization-server

Authorization-server metadata at /.well-known/oauth-authorization-server (RFC 8414) and protected-resource metadata at /.well-known/oauth-protected-resource (RFC 9728). The JWKS used to verify access-token signatures lives at /oauth/jwks.json. Clients should fetch these to discover the authorize, token, and registration endpoints, never hard-code them.

No parameters. Returns JSON with issuer, authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, scopes_supported, code_challenge_methods_supported, and related metadata.

POST/oauth/register

Dynamic Client Registration per RFC 7591. Unauthenticated and rate-limited to 5/hour per IP. Only RFC 7591 fields are persisted (extra fields are dropped). Redirect URIs must be HTTPS (any host) or HTTP loopback (localhost / 127.0.0.1); custom schemes like javascript:, data:, file: are rejected. Maximum 10 redirect URIs per client; client_name capped at 200 chars; URIs capped at 2048 chars.

JSON body: redirect_uris (required array), client_name, grant_types (defaults to authorization_code refresh_token), token_endpoint_auth_method (none for public PKCE clients, client_secret_post for confidential), scope.

GET/oauth/authorize

Renders an in-app consent screen. On approval, redirects the user back to redirect_uri with a single-use code (10-minute TTL) and the original state. PKCE-S256 is mandatory; plain challenges are rejected.

Params: response_type=code (required), client_id (required), redirect_uri (required, must match a registered URI exactly), code_challenge (required), code_challenge_method=S256 (required), scope (space-separated: mcp:read mcp:write), state, resource (RFC 8707 resource indicator).

POST/oauth/token

Exchanges an authorization code for an access token + refresh token, or refreshes an access token. Uses application/x-www-form-urlencoded. Rate-limited to 60/minute per IP. Refresh responses return the same reusable refresh token, and all credentials expire at the fixed one-year authorization deadline.

Body: grant_type (authorization_code or refresh_token), client_id (required), client_secret (required for confidential clients), and either {code, code_verifier, redirect_uri} OR {refresh_token, optional scope for downscoping}.

Scopes & Audience Verification

Two scopes are defined. mcp:read grants access to every read tool (list_*, get_*). mcp:write additionally grants the write tools (create_prompts, create_competitor, create_collection, assign_prompt_tags, create_annotation, create_intelligence_task, launch_recommendations, create_technical_geo_report). A token issued with only mcp:read cannot invoke write tools, both tools/list hides them and direct tools/call returns an error. The JWT aud claim must equal the resource server URL; tokens with a different audience are rejected at /api/v1/mcp.

When refreshing a token, you MAY pass a narrower scope, anything broader than the original grant returns invalid_grant.

Changelog

The three most recent API changes. The full history lives on its own page.

• 2026-08: Native Rust CLI and official SDKs. CLI v2 replaces the JavaScript implementation with native binaries for macOS, Linux and Windows while preserving the existing configuration and profile format. Typed commands cover all 71 REST operations, with JSON, table and CSV output plus a direct REST command. Official generated clients are now maintained for TypeScript, Python, Go, Java, Kotlin, C#, PHP, Ruby, Rust, Swift, Dart and R. The OpenAPI document uses OpenAPI 3.0-compatible nullable fields so every client can be generated with the same pinned toolchain.
• 2026-08: Automatic annotations and all-plan access (v1.23.0). Annotations are now available on every plan, including Starter and trial accounts. Rows returned by GET /annotations and the MCP list_annotations tool include origin: manual, automation, geo_test, or platform. Automatic project annotations record daily prompt-set changes, enabled AI model changes, and tracking frequency changes. Existing fields and write behavior are unchanged.
• 2026-08: Share of Voice sample sizes and per-model grouping (v1.22.0). GET /metrics/sov now returns a periods array with, per bucket, the total mentions the shares were computed on (the sample size: a bucket with 1-3 mentions reads as 100/50/33.33 and should be treated as low-sample) and a partial flag marking buckets still collecting data or clipped by the requested window. Each current row also carries precomputed deltas: previous_share (last complete bucket) and avg_share (mean over complete buckets with data; partial buckets excluded). Existing fields are unchanged. The MCP get_sov tool gains group_by=model returning one compact per-model share comparison per call (add include_series=true for per-model trend series), every project-scoped MCP tool now accepts the project domain or exact name/brand name in project_id besides the numeric id, MCP metric responses include an app_url source link, and MCP metric tools render interactive widgets in hosts that support them: share-of-voice donut, visibility summary card, metric-over-time line chart (get_timeseries) and top cited domains (get_top_sources).

View the full API changelog