Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: LLM Pulse Shopping & Ads 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: Shopping & Ads
description: 'Commercial surfaces inside AI answers: the product cards models return, the paid placements that run alongside them, and the local businesses they list for prompts with local intent. Shopping and ads need the Scale plan or above; local businesses are available on every plan.'
paths:
/dimensions/shopping:
get:
tags:
- Shopping & Ads
summary: List shopping results
x-llms-description: Shopping results returned inside AI answers, per distinct product (view=products) or per selling merchant (view=merchants), with appearance counts, price range and rating (Scale plan or above).
operationId: listShopping
x-mcp-tool: list_shopping_products
x-plan: scale
description: Product cards returned inside AI answers. view=products (default) returns one row per distinct product, merged across executions, with its appearance count, price range, rating and whether it is yours, plus a currency_count saying how many currencies it was priced in (above 1 means the row reports its highest-priced listing and min_price may be another currency); view=merchants returns one row per selling merchant, with a currency field naming the money its price range and average are expressed in (AI answers price each market in its own currency, so a merchant that sells in more than one reports the currency most of its prices use). Every response also carries a totals block matching the KPI cards in the app, whose avg_price is computed inside the single currency named by avg_price_currency. Requires the Scale plan or above.
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- name: view
in: query
required: false
schema:
type: string
enum:
- products
- merchants
default: products
description: 'Row shape: one per distinct product, or one per merchant'
- name: owned
in: query
required: false
schema:
type: boolean
description: Return only products identified as the tracked brand's own. On view=merchants this narrows to the merchants selling those products; the totals block stays account-wide.
- name: order
in: query
required: false
schema:
type: string
enum:
- appearances
- price
- rating
- title
- products
- avg_price
- avg_rating
- merchant
description: Sort field; the allowed set depends on view
- name: direction
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- name: query
in: query
required: false
schema:
type: string
description: Case-insensitive substring filter on the product title
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/Prompt'
- $ref: '#/components/parameters/PromptType'
- $ref: '#/components/parameters/BrandKind'
- $ref: '#/components/parameters/Range'
- $ref: '#/components/parameters/ListingFrom'
- $ref: '#/components/parameters/ListingTo'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Paginated shopping rows plus totals
'422':
$ref: '#/components/responses/UnprocessableEntity'
/dimensions/ads:
get:
tags:
- Shopping & Ads
summary: List AI ad placements
x-llms-description: Paid placements returned inside AI answers, per advertising domain (view=advertisers) or per individual placement (view=ads), with counts and positions (Scale plan or above).
operationId: listAds
x-mcp-tool: list_ads
x-plan: scale
description: Paid placements returned inside AI answers. view=advertisers (default) returns one row per advertising domain with its placement count, prompt reach and average and best position; view=ads returns the individual placements with title, snippet, position and the prompt that triggered them. Position 1 is the best slot, so a LOWER average position is better. Requires the Scale plan or above.
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- name: view
in: query
required: false
schema:
type: string
enum:
- advertisers
- ads
default: advertisers
description: 'Row shape: one per advertising domain, or one per placement'
- name: owned
in: query
required: false
schema:
type: boolean
description: Return only placements identified as the tracked brand's own (view=ads)
- name: order
in: query
required: false
schema:
type: string
enum:
- ads
- prompts
- avg_position
- domain
- recent
- oldest
- position
description: Sort field; the allowed set depends on view
- name: direction
in: query
required: false
schema:
type: string
enum:
- asc
- desc
description: Sort direction for view=advertisers. Defaults to desc, except avg_position and domain which default to asc.
- name: query
in: query
required: false
schema:
type: string
description: Case-insensitive substring filter on the ad title, domain or snippet
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/Prompt'
- $ref: '#/components/parameters/PromptType'
- $ref: '#/components/parameters/BrandKind'
- $ref: '#/components/parameters/Range'
- $ref: '#/components/parameters/ListingFrom'
- $ref: '#/components/parameters/ListingTo'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Paginated ad rows plus totals
'422':
$ref: '#/components/responses/UnprocessableEntity'
/dimensions/local_businesses:
get:
tags:
- Shopping & Ads
summary: List local businesses
x-llms-description: Local businesses listed inside AI answers, one row per business at its address, with appearances, prompts, average rating and position, and whether it is yours or a competitor (every plan).
operationId: listLocalBusinesses
x-mcp-tool: list_local_businesses
description: 'Local businesses (shops, restaurants, services) listed inside AI answers, one row per business: its name at its address, so two locations of a chain are two rows. Each row carries its appearance count, the number of prompts that listed it, its average rating and average position in the list, its review count, and whether it is yours or a tracked competitor. Every response also carries a totals block matching the KPI cards in the app. Local business lists come from a subset of models and only for prompts with local intent. Available on every plan.'
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- name: owned
in: query
required: false
schema:
type: boolean
description: Return only listings identified as the tracked brand's own locations. The totals block stays account-wide.
- name: order
in: query
required: false
schema:
type: string
enum:
- appearances
- business
- rating
- reviews
- avg_position
- prompts
default: appearances
description: Sort field
- name: direction
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: desc
- name: query
in: query
required: false
schema:
type: string
description: Case-insensitive substring filter on the business name or address
- $ref: '#/components/parameters/Model'
- $ref: '#/components/parameters/CollectionId'
- $ref: '#/components/parameters/CountryCode'
- $ref: '#/components/parameters/LanguageCode'
- $ref: '#/components/parameters/Prompt'
- $ref: '#/components/parameters/PromptType'
- $ref: '#/components/parameters/BrandKind'
- $ref: '#/components/parameters/Range'
- $ref: '#/components/parameters/ListingFrom'
- $ref: '#/components/parameters/ListingTo'
- $ref: '#/components/parameters/Output'
responses:
'200':
description: Paginated local business rows plus totals
content:
application/json:
schema:
$ref: '#/components/schemas/LocalBusinessesResponse'
'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.
Prompt:
name: prompt
in: query
schema:
type: integer
minimum: 1
description: Filter by prompt ID. An id that is not a plain positive number, or that names no prompt of the project, 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.
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.'
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.'
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
schemas:
LocalBusinessesTotals:
type: object
properties:
businesses:
type: integer
your_businesses:
type: integer
appearances:
type: integer
avg_rating:
type:
- number
- 'null'
executions_with_local_businesses:
type: integer
LocalBusinessesResponse:
type: object
properties:
project_id:
type: integer
page:
type: integer
per_page:
type: integer
total:
type: integer
totals:
$ref: '#/components/schemas/LocalBusinessesTotals'
data:
type: array
items:
$ref: '#/components/schemas/LocalBusiness'
request_id:
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
LocalBusiness:
type: object
properties:
business_key:
type: string
description: 'Stable grouping key: the lowercased name and address'
title:
type: string
address:
type:
- string
- 'null'
domain:
type:
- string
- 'null'
url:
type:
- string
- 'null'
phone:
type:
- string
- 'null'
avg_rating:
type:
- number
- 'null'
reviews:
type:
- integer
- 'null'
avg_position:
type:
- number
- 'null'
description: Average rank of the business in the answer's list (1 = first)
prompts:
type: integer
appearances:
type: integer
is_client:
type: boolean
competitor_id:
type:
- integer
- 'null'
competitor_name:
type:
- string
- 'null'
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