LLM Pulse Sentiments API
Sentiment records with their comments, topics and scores, plus the category catalog used to label them.
Sentiment records with their comments, topics and scores, plus the category catalog used to label them.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/llmpulse-ai:llmpulse-ai-sentiments-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: LLM Pulse Sentiments 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: Sentiments
description: Sentiment records with their comments, topics and scores, plus the category catalog used to label them.
paths:
/dimensions/sentiments:
get:
tags:
- Sentiments
summary: List sentiment categories (Growth plan or above)
x-llms-description: List sentiment categories (metric keys + labels + colors). For records use /sentiments.
operationId: listSentimentCategories
x-mcp-tool: list_sentiments
x-plan: growth
description: Sentiment metric keys + labels + colors. For records, use /sentiments. Requires the Growth plan; lower tiers receive ERR_PLAN_REQUIRED.
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Sentiment buckets
'403':
$ref: '#/components/responses/GrowthPlanRequired'
/sentiments:
get:
tags:
- Sentiments
summary: List sentiment records (Growth plan or above)
x-llms-description: Paginated sentiment analysis records with comments, topics, scores; filterable by analysis level and brand_only.
operationId: listSentimentRecords
x-mcp-tool: list_detailed_sentiments
x-plan: growth
description: Requires the Growth plan; lower tiers receive ERR_PLAN_REQUIRED.
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: competitor_id
in: query
schema:
type: integer
minimum: 1
description: Keep the sentiments about this competitor. An id that is not a plain positive number, or that names no competitor of the project, returns 422 ERR_INVALID_PARAM.
- name: brand_only
in: query
schema:
type: boolean
description: true keeps only the sentiments about your own brand.
- name: analysis
in: query
schema:
type: string
description: 'One sentiment level or a comma-separated list: very_positive, positive, neutral, negative, very_negative'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/ListingFrom'
- $ref: '#/components/parameters/ListingTo'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: Paginated sentiments
content:
application/json:
schema:
$ref: '#/components/schemas/SentimentsResponse'
'403':
$ref: '#/components/responses/GrowthPlanRequired'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/reports/sentiment/topics:
get:
tags:
- Sentiments
summary: Sentiment by topic (Growth plan or above)
x-llms-description: 'The Sentiment page''s Topics table: analyzed mentions per topic with positive, neutral and negative counts, shares and net sentiment, under the page filters.'
operationId: getSentimentTopics
x-mcp-tool: get_sentiment_topics
x-plan: growth
description: 'One row per topic AI answers associate with the brand (topics are matched case-insensitively), with its analyzed mentions, the positive (very positive included), neutral and negative counts, their shares on a 0-100 scale and the net sentiment score ((positive - negative) / mentions x 100). The same rows and filters as the Topics tab of the Sentiment page: the window defaults to the last 28 days, `brand` empty counts your own brand, `all` every brand and a competitor id that competitor. Requires the Growth plan; lower tiers receive ERR_PLAN_REQUIRED.'
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: range
in: query
schema:
type: integer
description: Number of days to look back, today included (default 28, like the Sentiment page). from or to win over it, but a value that is not a plain positive number returns 422 ERR_INVALID_PARAM even beside them.
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/BrandKind'
- name: analysis
in: query
schema:
type: string
description: 'One sentiment level or a comma-separated list: very_positive, positive, neutral, negative, very_negative'
- name: topic
in: query
schema:
type: string
description: Only sentiments tagged with this topic (case-insensitive)
- name: query
in: query
schema:
type: string
description: Only sentiments whose answer or prompt text contains this text
- name: brand
in: query
schema:
type: string
description: Whose sentiment to count. Empty or omitted for your own brand, all for every brand, or a competitor id (an unknown id returns ERR_INVALID_PARAM).
- name: sort
in: query
schema:
type: string
enum:
- mentions
- name
- positive
- negative
- neutral
- net_score
default: mentions
description: 'Sort column: mentions, name (the topic or tag), positive, negative or neutral (their shares) or net_score. Ties sort by name.'
- name: sort_dir
in: query
schema:
type: string
enum:
- desc
- asc
default: desc
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Paginated topic rows
content:
application/json:
schema:
$ref: '#/components/schemas/SentimentTopicsResponse'
'403':
$ref: '#/components/responses/GrowthPlanRequired'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/reports/sentiment/tags:
get:
tags:
- Sentiments
summary: Sentiment by tag (Growth plan or above)
x-llms-description: 'The Sentiment page''s Tags table: analyzed mentions per tag with positive, neutral and negative counts, shares and net sentiment, under the page filters.'
operationId: getSentimentTags
x-mcp-tool: get_sentiment_tags
x-plan: growth
description: One row per tag of the project with at least one analyzed mention, with the positive (very positive included), neutral and negative counts, their shares on a 0-100 scale and the net sentiment score. A mention counts once for every tag its prompt carries, as on the Sentiment page. Same filters as GET /reports/sentiment/topics. Requires the Growth plan; lower tiers receive ERR_PLAN_REQUIRED.
parameters:
- $ref: '#/components/parameters/ProjectId'
- name: range
in: query
schema:
type: integer
description: Number of days to look back, today included (default 28, like the Sentiment page). from or to win over it, but a value that is not a plain positive number returns 422 ERR_INVALID_PARAM even beside them.
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/BrandKind'
- name: analysis
in: query
schema:
type: string
description: 'One sentiment level or a comma-separated list: very_positive, positive, neutral, negative, very_negative'
- name: topic
in: query
schema:
type: string
description: Only sentiments tagged with this topic (case-insensitive)
- name: query
in: query
schema:
type: string
description: Only sentiments whose answer or prompt text contains this text
- name: brand
in: query
schema:
type: string
description: Whose sentiment to count. Empty or omitted for your own brand, all for every brand, or a competitor id (an unknown id returns ERR_INVALID_PARAM).
- name: sort
in: query
schema:
type: string
enum:
- mentions
- name
- positive
- negative
- neutral
- net_score
default: mentions
description: 'Sort column: mentions, name (the topic or tag), positive, negative or neutral (their shares) or net_score. Ties sort by name.'
- name: sort_dir
in: query
schema:
type: string
enum:
- desc
- asc
default: desc
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Paginated tag rows
content:
application/json:
schema:
$ref: '#/components/schemas/SentimentTagsResponse'
'403':
$ref: '#/components/responses/GrowthPlanRequired'
'422':
$ref: '#/components/responses/UnprocessableEntity'
components:
parameters:
PerPage:
name: per_page
in: query
schema:
type: integer
default: 20
maximum: 100
minimum: 1
Output:
name: output
in: query
schema:
type: string
enum:
- flat
- csv
description: Rectangular output for BI tools (Tableau, Excel, Sheets, ELT). Omit for the default nested JSON. 'flat' returns the same metadata plus 'columns' and 'rows'; 'csv' returns those rows as text/csv. Errors are always returned as JSON.
ListingFrom:
name: from
in: query
schema:
type: string
format: date-time
description: Start of the window. Sent alone, the window runs from it to the end of today. A from later than to, or a window longer than 1,500 days, returns 422 ERR_INVALID_PARAM.
ListingTo:
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. Sent without from, the window covers the 30 days that end on it.
CountryCode:
name: country_code
in: query
schema:
type: string
description: One ISO country code or a comma-separated list (e.g. US,GB,DE)
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
Model:
name: model
in: query
schema:
type: string
enum:
- chatgpt
- perplexity
- ai_mode
- ai_overview
- gemini
- copilot
- amazon_rufus
- claude
- grok
- deepseek
- naver_ai
- baidu_ai
- meta_ai
- naver_ai_tab
- qwen
- doubao
- bing_ai_mode
description: 'Filter by one AI model. It must be a model enabled for the API key''s user: an unknown value, or a model the user has not enabled, returns 422 ERR_INVALID_PARAM with the valid values in the message.'
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.
responses:
UnprocessableEntity:
description: Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_INVALID_PARAM
message: invalid metrics
request_id: abc-123
GrowthPlanRequired:
description: Endpoint requires the Growth plan or above
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ERR_PLAN_REQUIRED
message: Growth plan or above required
request_id: abc-123
schemas:
PaginatedEnvelope:
type: object
description: Envelope shared by the paginated listings; each listing adds its own data rows
required:
- project_id
- page
- per_page
- total
- request_id
properties:
project_id:
type: integer
page:
type: integer
per_page:
type: integer
total:
type: integer
description: Rows matching the filters across every page
request_id:
type: string
SentimentRecord:
type: object
required:
- id
- prompt_execution_id
- prompt_text
- model
- analysis
- score
- comment
- topics
- competitor_id
- competitor_name
- is_brand_sentiment
- executed_at
- created_at
properties:
id:
type: integer
prompt_execution_id:
type: integer
prompt_text:
type: string
model:
type: string
enum:
- chatgpt
- perplexity
- ai_mode
- ai_overview
- gemini
- copilot
- amazon_rufus
- claude
- grok
- deepseek
- naver_ai
- baidu_ai
- meta_ai
- naver_ai_tab
- qwen
- doubao
- bing_ai_mode
analysis:
type: string
enum:
- very_positive
- positive
- neutral
- negative
- very_negative
score:
type:
- number
- 'null'
description: From -1 (very negative) to 1 (very positive)
comment:
type:
- string
- 'null'
topics:
type:
- string
- 'null'
description: Comma-separated topics
competitor_id:
type:
- integer
- 'null'
description: Null for a sentiment about the project's own brand
competitor_name:
type:
- string
- 'null'
description: Null for a sentiment about the project's own brand
is_brand_sentiment:
type: boolean
executed_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
SentimentBreakdownEnvelope:
type: object
required:
- from
- to
- brand
- sort
- sort_dir
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
brand:
$ref: '#/components/schemas/SentimentBreakdownBrand'
sort:
type: string
sort_dir:
type: string
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- ERR_MISSING_AUTH
- ERR_INVALID_API_KEY
- ERR_REVOKED_API_KEY
- ERR_INSUFFICIENT_SCOPE
- ERR_INSUFFICIENT_PERMISSION
- ERR_KEY_PROJECT_SCOPED
- ERR_PLAN_REQUIRED
- ERR_INTEGRATION_UNAVAILABLE
- ERR_GENERATION_FAILED
- ERR_ACCOUNT_INACTIVE
- ERR_DRAFT_NOT_FOUND
- ERR_DRAFT_STATE
- ERR_PROJECT_NOT_FOUND
- ERR_NOT_FOUND
- ERR_SEARCH_CONSOLE_NOT_CONNECTED
- ERR_SEARCH_CONSOLE_ACCESS_REVOKED
- ERR_SEARCH_CONSOLE_UPSTREAM
- ERR_CMS_NOT_CONNECTED
- ERR_CMS_ACCESS_REVOKED
- ERR_CMS_REJECTED
- ERR_CMS_UPSTREAM
- ERR_AI_TRAFFIC_NOT_CONNECTED
- ERR_WEB_ANALYTICS_NOT_CONNECTED
- ERR_WEB_ANALYTICS_INVALID_QUERY
- ERR_WEB_ANALYTICS_ACCESS_REVOKED
- ERR_WEB_ANALYTICS_UPSTREAM
- ERR_AGENT_TRAFFIC_NOT_CONNECTED
- ERR_INVALID_PARAM
- ERR_INVALID_RANGE
- ERR_LIMIT_REACHED
- ERR_QUOTA_EXCEEDED
- ERR_STALE_CONTENT
- ERR_RATE_LIMITED
message:
type: string
meta:
type: object
description: Extra detail for some codes. A not-connected or access-revoked error from the Search Console, AI traffic, web analytics or agent traffic endpoints carries connect_url, the in-app page where the user connects or reconnects the source. A prompt write refused because a launched pitch project's prompts are fixed carries reason pitch_prompts_frozen.
request_id:
type: string
SentimentBreakdownBrand:
type: object
required:
- type
properties:
type:
type: string
enum:
- project
- competitor
- all
id:
type:
- integer
- 'null'
description: The competitor id when type is competitor
name:
type:
- string
- 'null'
SentimentTopicsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedEnvelope'
- $ref: '#/components/schemas/SentimentBreakdownEnvelope'
- type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/SentimentTopicRow'
SentimentBreakdownCounts:
type: object
required:
- mentions
- positive
- neutral
- negative
- positive_pct
- neutral_pct
- negative_pct
- net_score
properties:
mentions:
type: integer
description: Analyzed mentions
positive:
type: integer
description: Positive and very positive
neutral:
type: integer
negative:
type: integer
description: Negative and very negative
positive_pct:
type: number
neutral_pct:
type: number
negative_pct:
type: number
net_score:
type: number
description: Positive minus negative, divided by mentions, times 100
SentimentsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedEnvelope'
- type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/SentimentRecord'
SentimentTagsResponse:
allOf:
- $ref: '#/components/schemas/PaginatedEnvelope'
- $ref: '#/components/schemas/SentimentBreakdownEnvelope'
- type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/SentimentTagRow'
SentimentTagRow:
allOf:
- type: object
required:
- tag_id
- tag
properties:
tag_id:
type: integer
tag:
type: string
- $ref: '#/components/schemas/SentimentBreakdownCounts'
SentimentTopicRow:
allOf:
- type: object
required:
- topic
properties:
topic:
type: string
- $ref: '#/components/schemas/SentimentBreakdownCounts'
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