LLM Pulse Shopping & Ads API

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.

GitHub OpenAPI

Operations 3

GET /dimensions/shopping List shopping results #
GET /dimensions/ads List AI ad placements #
GET /dimensions/local_businesses List local businesses #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/llmpulse-ai:llmpulse-ai-shopping-ads-api"
All apis
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.

Get an API 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 Specification

llmpulse-ai-shopping-ads-api-openapi.yml Raw ↑
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