Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: LLM Pulse AI Model Insights API
description: 'REST API for the LLM Pulse AI visibility platform. Track brand mentions, citations, sentiment, and Share of Voice across AI-generated answers (ChatGPT, Perplexity, Gemini, Google AI Overviews, Google AI Mode, and optional add-on models). Includes the MCP (Model Context Protocol) endpoint for AI clients. MCP is available on every plan and during eligible trials via OAuth 2.1, with Bearer-token API keys also accepted for headless integrations on the Scale plan or above. Full machine-readable reference at https://llmpulse.ai/api-docs/llms-full.txt. An API key can be limited to one or several projects when it is created, and the set never changes. Such a key sees only those projects: any other project id, domain or name answers ERR_PROJECT_NOT_FOUND exactly like a project that does not exist, listings return only those projects'' rows, and operations on the whole account (creating or deleting a project, the project draft wizard) answer ERR_KEY_PROJECT_SCOPED. Operations carry vendor extensions: x-plan is the plan or entitlement the endpoint requires beyond an API key (growth, scale or reputation_access), x-write marks endpoints that need a read and write key, x-mcp-tool names the MCP tool that returns the same data, x-mcp-plan gives that tool''s plan where it differs, and x-rest-only explains an endpoint with no MCP tool. Parameters are read strictly, on REST and MCP alike: a value outside a documented enum, a boolean other than true, false, 1 or 0, an id or count that is not a plain positive number (12abc, 1.0 or 0), an id of a record the project does not have, or a from later than to answers 422 ERR_INVALID_PARAM naming the parameter, never an ignored filter. A listed value, in a query or a request body, matches in any letter case and is read in its documented spelling (granularity=Week reads as week, aggregation_type=BYPAGE as byPage, event_type=Mention.Created as mention.created). page and per_page keep their own rule: a value that is not a number reads as absent and an out-of-range one is clamped.'
version: 1.97.0
contact:
name: LLM Pulse Support
url: https://llmpulse.ai
email: info@llmpulse.ai
license:
name: Proprietary
url: https://llmpulse.ai/terms
servers:
- url: https://api.llmpulse.ai/api/v1
description: Production API
security:
- BearerAuth: []
tags:
- name: AI Model Insights
description: Aggregate AI Model Insights report endpoints (summary, position distribution, AI Overview results). All place each answer on the day it was created (Europe/Madrid time), as the app does, and share a standard actor shape.
paths:
/reports/ai_model_insights/summary:
get:
tags:
- AI Model Insights
summary: AI Model Insights summary
x-llms-description: 'AI Model Insights summary: per-model mentions, citations, sentiment, weighted visibility, actor matrices.'
operationId: getAiModelInsightsSummary
x-mcp-tool: get_ai_model_summary
description: Per-model mentions, citations, brand net sentiment with raw counts, weighted visibility totals/shares, plus actor matrices. All actor entries use the standard shape `{ type, id, competitor_id, name, domain }` with bare (scheme-less) domains. Rows cover the AI models the account has enabled or that answered in the window. A share, net sentiment or market share value with nothing behind it is null; counts, totals and weighted visibility scores stay 0.
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Range'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Granularity'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/PromptType'
- $ref: '#/components/parameters/BrandKind'
- $ref: '#/components/parameters/Competitors'
responses:
'200':
description: Summary
content:
application/json:
schema:
$ref: '#/components/schemas/AiModelInsightsSummaryResponse'
/reports/ai_model_insights/position_distribution:
get:
tags:
- AI Model Insights
summary: Position distribution comparison
x-llms-description: Per-model position distribution comparison (Position 1, 2-3, 4-7, 8+) for one or two brands.
operationId: getAiModelPositionDistribution
x-mcp-tool: get_ai_model_position_distribution
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Range'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Granularity'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/PromptType'
- $ref: '#/components/parameters/BrandKind'
- name: model
in: query
schema:
type: string
enum:
- chatgpt
- ai_mode
- ai_overview
- perplexity
- gemini
- naver_ai
- baidu_ai
- naver_ai_tab
- qwen
- doubao
- bing_ai_mode
description: Restrict the comparison to one AI model of AI Model Insights, whether or not that model is enabled for the API key's user. Any other value returns 422 ERR_INVALID_PARAM (invalid model).
- name: brand1
in: query
schema:
type: integer
description: Competitor ID for the first comparison brand (omit to compare project brand)
- name: brand2
in: query
schema:
type: integer
responses:
'200':
description: Bucketed position totals + chart-ready series
/reports/ai_model_insights/ai_overview_results:
get:
tags:
- AI Model Insights
summary: Google AI Overview result availability
x-llms-description: Google AI Overview result-availability data with by-prompt result-rate table.
operationId: getAiOverviewResults
x-mcp-tool: get_ai_overview_results
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Range'
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Granularity'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/PromptType'
- $ref: '#/components/parameters/BrandKind'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: AI Overview result-availability data + per-prompt table
components:
schemas:
AiModelMentionsRow:
allOf:
- $ref: '#/components/schemas/AiModelInsightsModel'
- type: object
properties:
mentions_count:
type: integer
description: Brand mentions in the model's answers; 0 when it has none
share_of_total:
type:
- number
- 'null'
description: The model's percentage (0-100) of total_mentions; null when total_mentions is 0
AiModelInsightsModel:
type: object
properties:
model:
type: string
description: AI model key, as /dimensions/models lists it
label:
type: string
description: Display name of the model
color:
type: string
description: Hex color the app charts the model with
AiModelInsightsFiltersEcho:
type: object
description: The filters the summary was computed with, as the server resolved them. A filter that was not given is left out, except granularity and competitors.
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
granularity:
type: string
description: day, week or month; day when not given
country_code:
type: string
description: Comma-separated country codes
language_code:
type: string
description: Comma-separated language codes
collection_id:
type: string
description: Comma-separated collection ids
prompt_type:
type: string
description: Comma-separated prompt types
brand_kind:
type: string
competitors:
type: array
items:
type: integer
description: Competitor ids from the competitors parameter; empty when it was not given
AiModelRateMatrix:
type: object
description: 'Each actor''s rate within each model: mentions of the actor (mentions_market_share), or answers citing it (citations_market_share), per answer of the model. Rates are independent, so the actors of a model can add up to more or less than 100.'
properties:
denominators_by_model:
type: object
description: Answers of each model in the window, keyed by model
additionalProperties:
type: integer
actors:
type: array
description: The project and each competitor with a mention (or citation) in the window (only the competitors given in competitors, when it is given), by total descending
items:
$ref: '#/components/schemas/AiModelRateMatrixActor'
AiModelSentimentMatrixActor:
type: object
description: An actor (the standard actor shape) with one net sentiment cell per model
properties:
type:
type: string
enum:
- project
- competitor
id:
type: integer
description: Project id, or competitor id
competitor_id:
type:
- integer
- 'null'
description: Null for the project, the competitor id otherwise
name:
type: string
domain:
type:
- string
- 'null'
description: Bare (scheme-less) domain. Null for the project actor when the project has no URL.
total_sentiments:
type: integer
description: The actor's sentiment verdicts summed over the models
models:
type: object
description: One cell per model, keyed by model
additionalProperties:
$ref: '#/components/schemas/AiModelSentimentCell'
AiModelWeightedVisibilityMatrixActor:
type: object
description: An actor (the standard actor shape) with one AI Visibility Score cell per model
properties:
type:
type: string
enum:
- project
- competitor
id:
type: integer
description: Project id, or competitor id
competitor_id:
type:
- integer
- 'null'
description: Null for the project, the competitor id otherwise
name:
type: string
domain:
type:
- string
- 'null'
description: Bare (scheme-less) domain. Null for the project actor when the project has no URL.
total_weighted_visibility_score:
type: number
description: The actor's AI Visibility Score across the enabled models, its points there divided by the project's tracking runs with answers in them, so actors compare
models:
type: object
description: One cell per model, keyed by model
additionalProperties:
$ref: '#/components/schemas/AiModelWeightedVisibilityCell'
AiModelSentimentCell:
type: object
properties:
value:
type:
- number
- 'null'
description: The actor's net sentiment in the model, positive_count minus negative_count as a percentage (-100 to 100) of total_sentiments; null when total_sentiments is 0
total_sentiments:
type: integer
description: The actor's sentiment verdicts in the model's answers
positive_count:
type: integer
description: Positive and very positive verdicts
negative_count:
type: integer
description: Negative and very negative verdicts
AiModelCitationsRow:
allOf:
- $ref: '#/components/schemas/AiModelInsightsModel'
- type: object
properties:
citations_count:
type: integer
description: Citations of the brand's URLs in the model's answers; 0 when it has none
share_of_total:
type:
- number
- 'null'
description: The model's percentage (0-100) of total_citations; null when total_citations is 0
AiModelWeightedVisibilityRow:
allOf:
- $ref: '#/components/schemas/AiModelInsightsModel'
- type: object
properties:
weighted_visibility_score:
type: number
description: The brand's AI Visibility Score in the model, its points there divided by the days the model answered; 0 when it has none
share_of_total:
type:
- number
- 'null'
description: The model's percentage (0-100) of the brand's AI Visibility Score points; null when the brand has none
AiModelRateCell:
type: object
properties:
value:
type:
- number
- 'null'
description: numerator as a percentage (0-100) of denominator; null when the model has no answers in the window
numerator:
type: integer
description: Mentions of the actor (or answers citing it) in the model's answers
denominator:
type: integer
description: Answers of the model in the window
AiModelInsightsSummaryResponse:
type: object
description: 'One entry per AI model the account has enabled or that answered in the window, in the in-app column order: the models list, which every per-model list and map in summary follows. A share, net sentiment or market share value with nothing behind it is null, because 0 is a real value; counts, totals and weighted visibility scores stay 0.'
properties:
project_id:
type: integer
from:
type: string
format: date-time
to:
type: string
format: date-time
filters:
$ref: '#/components/schemas/AiModelInsightsFiltersEcho'
models:
type: array
description: The AI models the account has enabled or that answered in the window, in the in-app column order
items:
$ref: '#/components/schemas/AiModelInsightsModel'
summary:
type: object
properties:
mentions_by_model:
type: object
properties:
total_mentions:
type: integer
description: Brand mentions across the models
models:
type: array
items:
$ref: '#/components/schemas/AiModelMentionsRow'
citations_by_model:
type: object
properties:
total_citations:
type: integer
description: Citations of the brand's URLs across the models
models:
type: array
items:
$ref: '#/components/schemas/AiModelCitationsRow'
brand_net_sentiment_by_model:
type: object
properties:
total_sentiments:
type: integer
description: Brand sentiment verdicts across the models
models:
type: array
items:
$ref: '#/components/schemas/AiModelSentimentRow'
weighted_visibility_by_model:
type: object
properties:
total_weighted_visibility_score:
type: number
description: The brand's AI Visibility Score across the enabled models, its points there divided by the tracking runs with answers in any of them (the Overview's number for the same filters; a model that answered while disabled keeps its row but stays out of it); 0 when it has none
models:
type: array
items:
$ref: '#/components/schemas/AiModelWeightedVisibilityRow'
mentions_market_share:
$ref: '#/components/schemas/AiModelRateMatrix'
citations_market_share:
$ref: '#/components/schemas/AiModelRateMatrix'
sentiment_market_share:
type: object
properties:
actors:
type: array
description: The project and each competitor with a sentiment verdict in the window (only the competitors given in competitors, when it is given), by total_sentiments descending
items:
$ref: '#/components/schemas/AiModelSentimentMatrixActor'
weighted_visibility_market_share:
type: object
properties:
actors:
type: array
description: The project and each competitor with an AI Visibility Score in the window, 0 included (only the competitors given in competitors, when it is given), by total_weighted_visibility_score descending
items:
$ref: '#/components/schemas/AiModelWeightedVisibilityMatrixActor'
request_id:
type: string
AiModelSentimentRow:
allOf:
- $ref: '#/components/schemas/AiModelInsightsModel'
- type: object
properties:
sentiments_count:
type: integer
description: Brand sentiment verdicts in the model's answers
positive_count:
type: integer
description: Positive and very positive verdicts
negative_count:
type: integer
description: Negative and very negative verdicts
net_sentiment:
type:
- number
- 'null'
description: positive_count minus negative_count as a percentage (-100 to 100) of sentiments_count, neutral verdicts counted in the base; null when sentiments_count is 0
AiModelWeightedVisibilityCell:
type: object
properties:
value:
type: number
description: The actor's AI Visibility Score in the model, its points there divided by the project's tracking runs with answers in that model; 0 when it has none
AiModelRateMatrixActor:
type: object
description: An actor (the standard actor shape) with one rate cell per model
properties:
type:
type: string
enum:
- project
- competitor
id:
type: integer
description: Project id, or competitor id
competitor_id:
type:
- integer
- 'null'
description: Null for the project, the competitor id otherwise
name:
type: string
domain:
type:
- string
- 'null'
description: Bare (scheme-less) domain. Null for the project actor when the project has no URL.
total:
type: integer
description: The actor's numerators summed over the models
models:
type: object
description: One cell per model, keyed by model
additionalProperties:
$ref: '#/components/schemas/AiModelRateCell'
parameters:
PerPage:
name: per_page
in: query
schema:
type: integer
default: 20
maximum: 100
minimum: 1
Granularity:
name: granularity
in: query
schema:
type: string
enum:
- day
- week
- month
PromptType:
name: prompt_type
in: query
schema:
type: string
description: 'One prompt type or a comma-separated list: informational, navigational, commercial, transactional'
CountryCode:
name: country_code
in: query
schema:
type: string
description: One ISO country code or a comma-separated list (e.g. US,GB,DE)
Range:
name: range
in: query
schema:
type: integer
description: Number of days to look back (alternative to from/to, which win when both are given). A value that is not a plain positive number returns 422 ERR_INVALID_PARAM, even beside from/to.
LanguageCode:
name: language_code
in: query
schema:
type: string
description: One ISO language code or a comma-separated list (e.g. en,es,de)
CollectionId:
name: collection_id
in: query
schema:
type: string
pattern: ^\d+(,\d+)*$
example: 12,34
description: 'One collection/tag ID or a comma-separated list of IDs. A query value is always a string on the wire, so it is typed as one: the previous integer-or-string union made generators emit a wrapper type they could not serialize.'
From:
name: from
in: query
schema:
type: string
format: date-time
BrandKind:
name: brand_kind
in: query
schema:
type: string
enum:
- brand
- brand_other
- non_brand
description: 'Filter by brand kind: brand (own brand/products), brand_other (competitors/other brands), non_brand (generic, no brand named). For fair 1:1 brand-vs-competitor comparisons (visibility, share of voice), use non_brand: brand-focused prompts skew results toward the brand they name. The in-app Overview page applies non_brand by default.'
ProjectId:
name: project_id
in: query
required: true
schema:
type: integer
description: Project ID
Page:
name: page
in: query
schema:
type: integer
default: 1
minimum: 1
To:
name: to
in: query
schema:
type: string
format: date-time
description: End of the window. A date-only value such as 2026-09-01 covers that whole day. Pass a full timestamp to end the window earlier.
Competitors:
name: competitors
in: query
schema:
type: string
description: Comma-separated competitor IDs (a malformed or unknown ID returns ERR_INVALID_PARAM)
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: API key authentication. Keys are managed at https://llmpulse.ai/app/api_keys (Scale plan or above). Used for the REST API and as a headless option for /mcp. A key can be limited to one or several projects when it is created; the set cannot be changed later.
OAuth2:
type: oauth2
description: OAuth 2.1 with PKCE-S256 and Dynamic Client Registration. Accepted on /mcp only, available on every plan and during eligible trials. Discovery metadata at /.well-known/oauth-authorization-server.
flows:
authorizationCode:
authorizationUrl: https://api.llmpulse.ai/oauth/authorize
tokenUrl: https://api.llmpulse.ai/oauth/token
scopes:
mcp:read: Read data via MCP tools
mcp:write: Create resources via MCP write tools