NEW ChatGPT Ads is live Learn more

API Documentation

Access your AI visibility data programmatically. Build dashboards, ETL pipelines, and automate your workflows with our REST API and MCP integration.

Get Started Free Download LLMPulse API v1 Postman Collection

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.

Authentication

Use a Bearer token from your API Key.

Authorization: Bearer YOUR_API_KEY

Base URL

Use this base URL for all endpoints below. Examples already include the full path.

https://api.llmpulse.ai/api/v1

Using an AI agent? Read the llms.txt

We serve a machine-readable version of these docs so coding agents (Claude Code, Cursor, ChatGPT, etc.) can find the right endpoint without parsing this page.

/api-docs/llms.txt — short index, generated from the live route table.

/api-docs/llms-full.txt — full reference (every endpoint, every parameter).

100% UI-to-API parity — found a gap? We''ll close it

We aim for 100% UI-to-API parity — anything you can see in the LLM Pulse dashboard should be reachable through the API. If you find a gap, report it and we commit to implementing it, typically within hours to a few days.

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/*

API Playground

API Playground

Test API endpoints live 
curl -X GET "https://api.llmpulse.ai/api/v1/ping" -H "Authorization: Bearer YOUR_API_KEY"
\-- 
Response will appear here...

Sign up to get your API key and start testing

Get API Key

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 (also serves as 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.

  • Params: project_id (required).

GET /dimensions/prompts

Lists prompts in a project.

  • Params: project_id (required), collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page (≤100).

GET /dimensions/prompt_executions

Lists prompt executions in a project.

  • Params: project_id (required), model, collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page.

GET /dimensions/sources

Lists non-rejected sources produced by prompt executions.

  • Params: project_id (required), model, collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page.

GET /dimensions/mentions

Lists mentions created by your project.

  • Params: project_id (required), collection_id, prompt (prompt ID), from, to, page, per_page.

GET /dimensions/citations

Lists citations created by your project.

  • Params: project_id (required), collection_id, prompt (prompt ID), from, to, page, per_page.

GET /dimensions/competitor_mentions

Lists competitor mentions detected in your executions.

  • Params: project_id (required), competitors (CSV ids), prompt (prompt ID), from, to, page, per_page.

GET /dimensions/competitor_citations

Lists competitor citations detected in your executions.

  • Params: project_id (required), competitors (CSV ids), prompt (prompt ID), from, to, page, per_page.

GET /dimensions/all_mentions

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

  • Params: project_id (required), competitors (CSV ids), model, collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page.

GET /dimensions/all_citations

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

  • Params: project_id (required), competitors (CSV ids), model, collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page.

GET /dimensions/projects/:id

Get detailed information about a project including matching names, industry, business model, and statistics.

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.

  • Params: project_id (required), range, from, to, bot, company, group_by (bot|company), granularity (day|week|month).

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).

  • Params: project_id (required).

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).

  • Params: project_id (required), view (url|domain|host), page, per_page, order (group_key, total_responses, total_citations, citation_rate, avg_citation_position, first_seen_at, last_seen_at), direction, model, collection_id, country_code, language_code, prompt, from, to, query, source_type (owned|competitor|third_party|social_media|own_domain|ugc|background), sentiment (negative), content_gap (mentioned|gap). Invalid enum values return ERR_INVALID_PARAM.

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).

  • Params: project_id (required), :url_sha256 (64 hex chars).

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.

  • Params: project_id (required), range (default 28), from, to, granularity (day|week|month), collection_id, country_code, language_code, competitors (CSV of competitor IDs; unknown IDs → ERR_INVALID_PARAM).

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.

  • Params: project_id (required), range, from, to, granularity, collection_id, country_code, language_code, model (restrict to one model), brand1, brand2 (competitor IDs for the comparison brands; omit brand1 to compare the project brand).

GET /reports/ai_model_insights/ai_overview_results

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

  • Params: project_id (required), range, from, to (filters by executed_at), collection_id, country_code, language_code, granularity, page, per_page.

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.

  • Params: project_id (required), recommendation_type (ai_visibility|social_community|brand_building|sentiment_reputation), status (pending|processing|completed|failed), page, per_page. Invalid enum values return ERR_INVALID_PARAM.

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 <code>active</code>, <code>completed</code>, <code>archived</code>.

  • Params: project_id (required), :id (in URL), item_status (active|completed|archived), resolve_source_refs (default true).

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).

  • Params: project_id (required), model, collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page.

GET /answers/:id

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

  • Params: project_id (required), id (answer ID in URL).

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.

  • Params: project_id (required), model, competitor_id, brand_only, analysis (very_positive/positive/neutral/negative/very_negative), collection_id, prompt (prompt ID), country_code, language_code, from, to, page, per_page.

Prompts (Bulk Create)

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.

  • Body (JSON): project_id (required), prompts (array, required, max 100), country_code (required), language_code (required).

Content Intelligence

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

POST /intelligence_tasks

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

  • Body (JSON): project_id (required), task_type (required: brief, create, update, pr_insights, custom), prompt_id, custom_topic, user_instructions, output_language_code, existing_content, existing_content_url.

GET /intelligence_tasks

List content intelligence tasks for a project with optional filtering.

  • Params: project_id (required), task_type, status, page, per_page.

GET /intelligence_tasks/:id

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

  • Params: project_id (required), :id (task ID or public_id in URL).

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 /competitors

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

  • Body (JSON): project_id (required), brand_name (required), domain (required, URL is normalised), matching_names (optional array).

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.

  • Body (JSON): project_id (required), name (required), description (optional), prompt_ids (optional array — must belong to the project).

POST /prompts/assign_tags

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

  • Body (JSON): project_id (required), prompt_ids (required array), tag_ids (one-of), tag_names (one-of), create_missing (optional bool — auto-create unknown tag names).

POST /annotations

Mark a date in the project timeseries with a title + description. Requires the Growth plan or above (returns ERR_PLAN_REQUIRED otherwise).

  • Body (JSON): project_id (required), title (required), annotation_date (optional ISO YYYY-MM-DD; default today), description (optional), color (optional hex), annotation_category_id (optional — must belong to the project).

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.

  • Body (JSON): project_id (required), url (required), country_code (optional — defaults to the project country).

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).

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: same behavior as mentions (PERIOD TOTAL repeated daily with sticky carry when the period total is 0).
  • 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 citations 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: 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.

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:

Code HTTP Meaning
ERR_MISSING_AUTH 401 Missing or malformed Authorization header
ERR_INVALID_API_KEY 401 Token not recognized
ERR_REVOKED_API_KEY 403 Key revoked
ERR_PROJECT_NOT_FOUND 404 project_id not accessible by this user
ERR_NOT_FOUND 404 Resource not found
ERR_INVALID_PARAM 422 Validation failed (see message)
ERR_LIMIT_REACHED 422 Account prompt limit reached
ERR_QUOTA_EXCEEDED 422 Monthly intelligence task quota exceeded

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.

Available Tools

These tools are available to your AI assistant.

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

Tool Description Plan
list_projects List all projects accessible to the authenticated user. Returns project id and name. All
list_competitors List all competitors for a specific project. Returns competitor id, name, and domain. All
list_collections List all collections (tags) for a specific project. Returns collection id and name. All
list_tags List all tags for a specific project. In LLM Pulse, tags are represented by collections. All
list_models List all AI models that have data for a specific project. Returns model identifiers (e.g., chatgpt-4o, perplexity, gemini). All
list_locales List all countries and languages that have data for a specific project. Returns lists of country codes (e.g., US, ES) and language codes (e.g., en, es). All
list_sentiments List all sentiment categories with their metric keys, labels, and colors. Used for understanding sentiment data structure. All
list_prompts List prompts for a project with optional filtering by collection, locale, prompt_type, brand_kind, and date range. Returns paginated results with prompt id, prompt_text, collection_id, country_code, language_code, prompt_type, brand_kind, and last_executed_at. All
list_prompt_executions List prompt executions with model, success, execution timing, fan-out queries, and mention/citation presence. All
list_mentions List brand mentions for a project with optional filtering. Returns paginated results with mention id, name, prompt_id, prompt_execution_id, and created_at. All
list_citations List URL citations for a project with optional filtering. Returns paginated results with citation id, name, domain, prompt_id, prompt_execution_id, url, position, and created_at. All
list_competitor_mentions List competitor mentions for a project with optional competitor and prompt filters. All
list_competitor_citations List competitor citations for a project with optional competitor and prompt filters. All
list_all_mentions List all mentions (brand + competitor) for a project with actor_type field. Returns paginated results combining project and competitor mentions. All
list_all_citations List all citations (brand + competitor) for a project with actor_type field. Returns paginated results combining project and competitor citations. All
list_sources List sources (URLs cited by AI models) for a project with optional filtering. Returns paginated results with source id, prompt_execution_id, domain, url, and position. All
list_citation_groups List grouped citation intelligence data by URL, domain, or host, including citation rates, model breakdowns, and page-cache awareness. All
get_cited_url_details Get detailed URL-level citation intelligence for one cited URL, including page-cache metadata and mention evidence. All
list_cited_url_occurrences List every prompt execution where a specific cited URL appeared, with prompt text, answer preview, model, and citation position. All
get_cited_url_content Get sanitized cached page content plus page-cache metadata and mention snippets for one cited URL. All
get_timeseries Get time series metrics data for a project. Supports metrics like mentions, citations, mention_rate (also accepted as visibility), citation_rate, responses, ai_visibility_score (position-weighted visibility), avg_position, net_sentiment, and sentiment breakdowns. Returns data points over time for the project and optionally competitors. All
get_summary Get summary statistics for metrics over a time period. Returns total, min, max, and last values for each metric and actor. Built on top of timeseries data. All
get_prompt_summary Get per-prompt aggregated metrics (responses, mentions, citations, mention_rate, citation_rate, avg_mention_position, avg_position) with pagination and sorting. mention_rate (also accepted as visibility) is the percentage of responses mentioning the brand. Returns brand-only metrics broken down by individual prompt. Supports breakdown=model to get per-prompt per-model metrics. All
get_sov Get Share of Voice metrics - shows the relative share of mentions between the project and competitors over time. Returns current share percentages and breakdown by actor. All
get_top_sources Get top performing source domains for a project. Returns domains ranked by total responses or average mention rate (also accepted as avg_visibility), with pagination support. All
get_ai_model_summary Per-AI-model breakdown of mentions, citations, sentiment and weighted visibility for the brand and competitors, in a single call. USE THIS for any question that compares performance across AI models ("which model do I rank best on?", "ChatGPT vs Perplexity vs Gemini", "where am I most visible across models?"). Prefer this over calling get_summary multiple times with different model filters — get_ai_model_summary returns all models at once and avoids hitting the step limit. All
get_ai_model_position_distribution Get the AI Model Insights position-distribution comparison for the project brand and an optional competitor. All
get_ai_overview_results Get aggregate Google AI Overview result availability over time plus per-prompt breakdowns. All
list_answers List AI answers/responses with their content, prompt text, model, and basic metrics. Returns paginated results with truncated response text. All
get_answer Get detailed information about a single AI answer/response including full response text, mentions, citations, sentiments, and sources. All
list_detailed_sentiments List detailed sentiment analysis records with comments, topics, scores, and competitor information. This is different from list_sentiments which only returns sentiment categories. All
list_recommendations List read-only recommendation runs for a project, including type, status, summary, and counts. All
get_recommendation Get full details for one recommendation run, including items, source references, and report data. All
get_project_details Get detailed information about a project including matching names, industry, business model, primary products, target audience, and basic statistics. All
get_competitor_details Get detailed information about a competitor including matching names, mobile app IDs, and icon URLs. All
create_prompts Add prompts to a project in bulk. Validates against available prompt limits. Skips duplicates. All
create_intelligence_task Create a content intelligence task. task_type selects what is produced: "brief" = content brief/outline for a topic, "create" = full draft article, "update" = rewrite/improve existing content (requires existing_content or existing_content_url), "pr_insights" = PR/media angle analysis, "custom" = freeform output driven by user_instructions. Pass prompt_id to base the task on an existing prompt, or omit it for agentic mode (then custom_topic or user_instructions is required). Returns task ID for polling status with get_intelligence_task. All
create_competitor Add a competitor to a project. Validates against the plan's max competitor limit. Triggers async association recalculation. All
create_collection Create a tag (Collection) in a project. Optionally attach existing prompts in the same call. Tag name is unique per project (case-insensitive). All
assign_prompt_tags Attach tags (collections) to existing prompts in bulk. Provide tag_ids for known tags, or tag_names to look up by name (case-insensitive). Pass create_missing=true to create tag names that do not exist yet. Idempotent: re-running with the same input does not duplicate assignments. All
create_annotation Mark a date in the project timeseries with a title + description. Useful when the agent detects a notable change (campaign launch, product update, news event) and wants to flag it. Annotations are scoped to the project and visible to all members. Growth
launch_recommendations Re-generate AI-powered recommendations for a project. Costly (OpenAI calls, long-running job), so the tool returns a preview + a confirmation token; the user must click Confirm in the UI to actually launch the job. Each recommendation_type has a one-per-week regeneration cap (admins exempted). All
create_technical_geo_report Run the full technical GEO analysis bundle (crawlability, schema, content readiness, discoverability, site structure, robots.txt, llms.txt, AI visibility) for a given URL + country. Costly (multiple jobs, BrightData/OpenAI), so the tool returns a preview + confirmation token; the user must click Confirm in the UI to actually launch the reports. All
list_intelligence_tasks List content intelligence tasks for a project with optional filtering by type and status. All
get_intelligence_task Get a content intelligence task by ID, including status and result data when completed. All
get_agent_traffic Get aggregated AI bot traffic for a project from Cloudflare or uploaded server logs. Returns per-day request counts grouped by bot or by company. Available on Scale and above plans. Scale
list_agent_bots List the catalog of known AI bots (crawlers, assistants, search fetchers) and their parent companies. Use this to discover valid bot slugs and company names for the bot/company filters of get_agent_traffic. Returns each bot's slug, display name, company, category, and description. Available on Scale and above plans. Scale

Protocol

MCP uses JSON-RPC 2.0. Here's an example of listing available tools:

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. Access tokens are RS256-signed JWTs with a 1-hour TTL; refresh tokens last 30 days and are rotated on every use.

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 tokens are rotated on each use; the old refresh token is revoked immediately.

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

  • 2025-08: Initial public API docs (v1)
  • 2025-09: Metrics aligned with Overview (period totals with sticky, ratio-of-period-sums for visibility, propagation in avg_position), SOV breakdown, query filter in Top Sources, caching notes, Postman download & environment section
  • 2025-12: Sentiment metrics added to /metrics/timeseries (sentiment_very_positive/positive/neutral/negative/very_negative) and documented semantics
  • 2026-01: Added MCP (Model Context Protocol) endpoint for AI integrations with Claude, ChatGPT, and other AI assistants
  • 2026-02: Added ai_visibility_score metric (position-weighted visibility). New MCP tools: list_answers, get_answer, list_detailed_sentiments, get_project_details, get_competitor_details. New API endpoints: /answers, /sentiments, /dimensions/projects/:id, /dimensions/competitors/:id. Added responses metric (prompt execution count) and citation_rate metric (citations / responses x 100). API rate limits increased from 100 to 300 requests/minute. Added prompt filter to all metrics and dimensions endpoints.
  • 2026-03: New endpoint GET /metrics/prompt_summary for paginated per-prompt metrics (responses, mentions, citations, visibility, citation_rate) in a single request
  • 2026-04: New POST /prompts endpoint for bulk prompt creation (up to 100 per request). New Content Intelligence API: POST /intelligence_tasks to create tasks, GET /intelligence_tasks to list with filters, GET /intelligence_tasks/:id for full details and results. New MCP tools: create_prompts, create_intelligence_task, list_intelligence_tasks, get_intelligence_task. New error codes: ERR_LIMIT_REACHED (prompt quota), ERR_QUOTA_EXCEEDED (intelligence task quota), ERR_NOT_FOUND (resource not found).
  • 2026-04 (mid): Citation Intelligence API: GET /citation_intelligence/groups (cited-URL clusters with source/type filters), GET /citation_intelligence/urls/:url_sha256, /occurrences and /content for per-URL drill-down. AI Model Insights Reports API: GET /reports/ai_model_insights/summary, /position_distribution and /ai_overview_results. Recommendations API: GET /recommendations and GET /recommendations/:id. New MCP tools: list_citation_groups, get_cited_url_details, list_cited_url_occurrences, get_cited_url_content, get_ai_model_summary, get_ai_model_position_distribution, get_ai_overview_results, list_recommendations, get_recommendation, list_competitor_mentions, list_competitor_citations, list_prompt_executions, list_tags. Stricter enum validation across view, order, direction, granularity, model, source_type, sentiment, content_gap, recommendation_type, status — unknown values now return ERR_INVALID_PARAM instead of being silently ignored. source_type filter accepts owned, competitor, third_party in addition to classification lists. AI Overview results bucket by executed_at (not created_at), so retried/backfilled rows land in the correct day.
  • 2026-04 (late): Agent Analytics API (Scale+, Beta): GET /metrics/agent_traffic and GET /dimensions/agent_bots surface AI bot crawler traffic (GPTBot, PerplexityBot, ClaudeBot, OAI-SearchBot, Google-Extended, and ~25 others) from Cloudflare or CSV uploads. New MCP tool: get_agent_traffic. MCP tools/list is now filtered by your plan — tools you can't use no longer appear in the catalog, and direct calls to gated tools return a clean ERR_PLAN_REQUIRED instead of leaking schema. MCP auth boundaries hardened for member-of-owner access.
  • 2026-05: Projects now expose brand_name separately from name in API and MCP payloads. brand_name is the brand label sent to LLMs and shown in customer-facing charts; name remains the internal project label. name is still returned for back-compat. mention_rate accepted as a synonym for visibility in /metrics/* params and in MCP timeseries / summary / top_sources tools. Per-user AI model flags now apply to every read endpoint: API responses, metrics, dimensions, answers, sentiments and citations silently exclude models that aren't enabled for the API key's user (used by add-on models — Copilot, Claude, Grok, DeepSeek, Meta AI — so partners can sell them à la carte). Date-bucketed metrics standardized on Europe/Madrid for daily/weekly/monthly buckets, fixing off-by-one-day rows near midnight UTC.
  • 2026-05 (mid): Agent Write Endpoints (v1.5). API keys now expose a scope (read vs read_write); pre-existing keys treat full as a synonym of read_write. Mutation endpoints (POST/PATCH/PUT/DELETE) now require a read_write scope key and return 403 ERR_INSUFFICIENT_SCOPE otherwise. A second rate-limit bucket (60/min/key) is enforced on writes on top of the global 300/min/key budget. New REST endpoints: POST /competitors, POST /collections, POST /prompts/assign_tags (idempotent bulk tagging), POST /annotations (Growth+), POST /technical_geo_reports (full GEO bundle). New MCP write tools: create_competitor, create_collection, assign_prompt_tags, create_annotation, launch_recommendations (with pre-hoc user confirmation in the chat agent), create_technical_geo_report (idem). New error codes: ERR_INSUFFICIENT_SCOPE (403) for read-only keys hitting writes, ERR_PLAN_REQUIRED (403) for annotations on Starter.
  • 2026-05 (late): Prompt categorization filters. Every prompt is now auto-classified by prompt_type (search intent: informational, navigational, commercial, transactional) and brand_kind (brand = your own brand/products, brand_other = competitors or other brands, non_brand = generic, no brand named). Both are accepted as optional filters on /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources and /dimensions/prompts (which now also returns the two fields per prompt). Invalid values return ERR_INVALID_PARAM. The same filters are available as prompt_type / brand_kind args on the MCP tools get_timeseries, get_summary, get_sov and list_prompts.
  • 2026-05 (late): New recommendation type: Sentiment & Reputation (Scale+). recommendation_type on GET /recommendations (and the launch_recommendations MCP tool) now accepts sentiment_reputation in addition to ai_visibility, social_community and brand_building. It turns the last 30 days of brand sentiment (widening to 90 if sparse) — negative themes, comparative gaps where a competitor is praised, the cited sources behind negative answers, and weak reputation dimensions — into actionable recommendations. Requires the Scale plan or above; non-entitled users get ERR_INVALID_PARAM/plan errors.
  • 2026-05 (late): MCP available on every plan via OAuth. The MCP endpoint (POST /api/v1/mcp) now accepts OAuth 2.1 access tokens issued via Dynamic Client Registration (RFC 7591) and PKCE-S256. Any LLM Pulse user — including Starter, Growth and trial users — can connect ChatGPT, Claude, Gemini, Cursor or any other MCP-compatible client to their account by pasting the URL https://api.llmpulse.ai/api/v1/mcp into their client's MCP / connector settings; the client walks the user through an OAuth sign-in flow with no API key required. Per-tool plan gating still applies: write tools and advanced read tools that require Growth or Scale continue to be filtered out of tools/list for users without access. API-key auth (Authorization: Bearer …) is unchanged and remains the recommended path for headless integrations like Looker Studio, Zapier and CI scripts (Scale plan and above). Discovery endpoints (/.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, /oauth/jwks.json) and registration/authorize/token endpoints live under /oauth/*.