LLM Pulse Competitors API

The brands tracked alongside your own. Competitor ids are the actor_id values the metrics endpoints report against.

GitHub OpenAPI

Operations 6

GET /dimensions/competitors List competitors #
GET /dimensions/competitors/{id} Competitor details #
GET /competitors/suggestions List competitor suggestions #
POST /competitors Add a competitor #
PATCH /competitors/{id} Update a competitor #
DELETE /competitors/{id} Delete a competitor #

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-competitors-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-competitors-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: LLM Pulse Competitors 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: Competitors
  description: The brands tracked alongside your own. Competitor ids are the actor_id values the metrics endpoints report against.
paths:
  /dimensions/competitors:
    get:
      tags:
      - Competitors
      summary: List competitors
      x-llms-description: List competitors for a project (optionally including the project brand as actor_type=project).
      operationId: listCompetitors
      x-mcp-tool: list_competitors
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: include_project_brand
        in: query
        schema:
          type: boolean
          default: false
        description: When true, prepends the project brand with actor_type=project and is_own=true
      - $ref: '#/components/parameters/Output'
      responses:
        '200':
          description: Competitors
          content:
            application/json:
              schema:
                type: object
                properties:
                  project_id:
                    type: integer
                  competitors:
                    type: array
                    items:
                      $ref: '#/components/schemas/Competitor'
                  request_id:
                    type: string
  /dimensions/competitors/{id}:
    get:
      tags:
      - Competitors
      summary: Competitor details
      x-llms-description: 'Detailed info for one competitor: matching names, app store IDs, color.'
      operationId: getCompetitorDetails
      x-mcp-tool: get_competitor_details
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Competitor details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorDetails'
  /competitors/suggestions:
    get:
      tags:
      - Competitors
      summary: List competitor suggestions
      x-llms-description: The Competitors page's Suggested tab, competing brands the AI discovery proposed or the most cited domains not tracked yet.
      operationId: listCompetitorSuggestions
      x-mcp-tool: list_competitor_suggestions
      description: 'The two lists of the Suggested tab of the Competitors page. `basis=brands` (default) returns the competing brands the AI discovery proposed that are not tracked or rejected yet, with the names it would match and, when counted, how many answers name it (`mentions`). `basis=citations` returns the domains AI answers cite most that are not your own or tracked yet, with how many answers cite each (`citations`). `discovery` tells whether a discovery run is still loading. Read-only: it never starts a discovery run, which the page starts from its Discover button. Add a suggestion with POST /competitors.'
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: basis
        in: query
        schema:
          type: string
          enum:
          - brands
          - citations
          default: brands
      - name: query
        in: query
        schema:
          type: string
        description: Only suggestions whose brand name or domain contains this text
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Output'
      responses:
        '200':
          description: Paginated suggestions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorSuggestionsResponse'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /competitors:
    post:
      tags:
      - Competitors
      summary: Add a competitor
      x-llms-description: Add a competitor (brand_name + domain) to a project; respects the plan competitor cap.
      operationId: createCompetitor
      x-mcp-tool: create_competitor
      x-write: true
      description: Adds a competitor with its own citation URL matching rule. Honours the per-plan max competitors cap. A `domain` rule on the project's own domain, or one of its subdomains, or a `host` rule on the project's own host, returns ERR_INVALID_PARAM; a `path_prefix` rule on it is accepted. Requires a `read_write` scope API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_id
              - brand_name
              - domain
              properties:
                project_id:
                  type: integer
                brand_name:
                  type: string
                domain:
                  type: string
                  description: URL is accepted and normalised to host (e.g. https://www.openai.com → openai.com)
                matching_names:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    maxLength: 100
                  description: Extra names this competitor is matched by; brand_name is added automatically. At most 50 names in all, brand_name included, of up to 100 characters each; a longer list or name is refused with ERR_INVALID_PARAM (422)
                citation_match_mode:
                  type: string
                  enum:
                  - domain
                  - host
                  - path_prefix
                  default: domain
                  description: domain includes the registrable domain and all subdomains; host requires the exact hostname; path_prefix also requires citation_match_path
                citation_match_path:
                  type: string
                  description: Required when citation_match_mode=path_prefix, e.g. /es. Case-sensitive; trailing slash is optional; query and fragment are ignored
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorCreateResponse'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /competitors/{id}:
    patch:
      tags:
      - Competitors
      summary: Update a competitor
      x-llms-description: Update a competitor (brand_name, website domain or host, matching_names, color, citation rule). Name, website or rule changes re-run matching in the background.
      operationId: updateCompetitor
      x-mcp-tool: update_competitor
      x-write: true
      description: 'Updates brand_name, the competitor website domain or host, matching_names (full replacement list; the brand name is always included automatically), color and/or the citation URL matching rule. Website domain/host and citation-rule changes share one seven-day cooldown per competitor; other fields remain editable during the cooldown. Moving to a `domain` rule on the project''s own domain, or a `host` rule on its own host, returns ERR_INVALID_PARAM. Name, website or citation-rule changes re-run historical matching in the background: the competitor shows processing=true for a few minutes and further edits are rejected meanwhile. Requires a `read_write` scope API key.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_id
              properties:
                project_id:
                  type: integer
                brand_name:
                  type: string
                domain:
                  type: string
                  description: Website domain or host used for citation matching. A full URL is accepted and normalised to its host.
                matching_names:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    maxLength: 100
                  description: FULL replacement list of the names this competitor is matched by; brand_name is added automatically. At most 50 names in all, brand_name included, of up to 100 characters each; a longer list or name is refused with ERR_INVALID_PARAM (422) and nothing in the request is applied
                color:
                  type: string
                  description: 'Hex color, e.g. #1a2b3c'
                citation_match_mode:
                  type: string
                  enum:
                  - domain
                  - host
                  - path_prefix
                citation_match_path:
                  type: string
                  description: Required when changing citation_match_mode to path_prefix
      responses:
        '200':
          description: Updated
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      tags:
      - Competitors
      summary: Delete a competitor
      x-llms-description: Delete a competitor (irreversible; frees a competitor slot; its mentions, citations and sentiment are purged in the background, its ads, shopping products, local businesses and brand entities kept).
      operationId: deleteCompetitor
      x-mcp-tool: delete_competitor
      x-write: true
      description: Deletes a competitor (irreversible). It disappears immediately and frees a competitor slot; a background job then deletes its mentions, citations, sentiment and share of voice history. Its ads, shopping products, local businesses and brand entities are kept and move to the project or another competitor they match, or stay unattributed. Requires a `read_write` scope API key.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Deleted
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    ProjectId:
      name: project_id
      in: query
      required: true
      schema:
        type: integer
      description: Project ID
    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.
    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
  schemas:
    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
    CompetitorCreateResponse:
      type: object
      required:
      - project_id
      - competitor
      - competitors_remaining
      - total_competitors
      - request_id
      properties:
        project_id:
          type: integer
        competitor:
          type: object
          required:
          - id
          - brand_name
          - domain
          - citation_match_mode
          - citation_match_path
          - color
          - matching_names
          properties:
            id:
              type: integer
            brand_name:
              type: string
            domain:
              type: string
            citation_match_mode:
              $ref: '#/components/schemas/CitationMatchMode'
            citation_match_path:
              type:
              - string
              - 'null'
              description: Set only when citation_match_mode is path_prefix
            color:
              type:
              - string
              - 'null'
            matching_names:
              type: array
              items:
                type: string
        competitors_remaining:
          type:
          - integer
          - 'null'
          description: Competitors the plan still allows in this project; null when unlimited
        total_competitors:
          type: integer
        request_id:
          type: string
    CitationMatchMode:
      type: string
      description: 'How citations are attributed: domain (the domain and its subdomains), host (that exact host) or path_prefix (URLs under citation_match_path)'
      enum:
      - domain
      - host
      - path_prefix
    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
    CompetitorDiscoveryState:
      type: object
      required:
      - loading
      properties:
        status:
          type:
          - string
          - 'null'
          description: 'The last discovery run: pending, processing, completed or failed; null when none ever ran'
        loading:
          type: boolean
          description: A discovery run is in progress
        generated_at:
          type:
          - string
          - 'null'
          format: date-time
    CompetitorSuggestionsResponse:
      allOf:
      - $ref: '#/components/schemas/PaginatedEnvelope'
      - type: object
        required:
        - basis
        - discovery
        - data
        properties:
          basis:
            type: string
            enum:
            - brands
            - citations
          discovery:
            $ref: '#/components/schemas/CompetitorDiscoveryState'
          data:
            type: array
            items:
              $ref: '#/components/schemas/CompetitorSuggestion'
    Competitor:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        domain:
          type:
          - string
          - 'null'
          description: Bare (scheme-less) domain. Null only on the own-brand row (include_project_brand=true) when the project has no URL.
        matching_names:
          type: array
          items:
            type: string
          description: Alternative names matched as this competitor. Absent on the own-brand row
        citation_match_mode:
          $ref: '#/components/schemas/CitationMatchMode'
        citation_match_path:
          type:
          - string
          - 'null'
          description: Set only when citation_match_mode is path_prefix
        actor_type:
          type: string
          enum:
          - project
          - competitor
          description: Only present when include_project_brand=true
        is_own:
          type: boolean
          description: Only present when include_project_brand=true
    CompetitorSuggestion:
      type: object
      required:
      - id
      - domain
      - matching_names
      properties:
        id:
          type: string
          description: The suggestion key (brands) or the id of one citing source row (citations)
        domain:
          type: string
        brand_name:
          type:
          - string
          - 'null'
          description: The proposed brand name; null for a cited domain
        matching_names:
          type: array
          items:
            type: string
          description: The names a tracked competitor would be matched by; empty for a cited domain
        mentions:
          type:
          - integer
          - 'null'
          description: Answers naming the brand, when the discovery counted them (brands only)
        citations:
          type:
          - integer
          - 'null'
          description: Answers citing the domain (citations only)
    CompetitorDetails:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        brand_name:
          type: string
        domain:
          type: string
        matching_names:
          type:
          - array
          - 'null'
          items:
            type: string
        google_play_id:
          type:
          - string
          - 'null'
        app_store_id:
          type:
          - string
          - 'null'
        citation_match_mode:
          $ref: '#/components/schemas/CitationMatchMode'
        citation_match_path:
          type:
          - string
          - 'null'
          description: Set only when citation_match_mode is path_prefix
        google_play_name:
          type:
          - string
          - 'null'
          description: English app name on Google Play, when the competitor has an Android app
        app_store_name:
          type:
          - string
          - 'null'
          description: English app name on the App Store, when the competitor has an iOS app
        google_play_icon_url:
          type:
          - string
          - 'null'
        app_store_icon_url:
          type:
          - string
          - 'null'
        color:
          type:
          - string
          - 'null'
        processing:
          type: boolean
          description: True while the competitor's historical mentions are being recalculated
        created_at:
          type: string
          format: date-time
        request_id:
          type: string
  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
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_PROJECT_NOT_FOUND
              message: project_not_found
            request_id: abc-123
    InsufficientScope:
      description: API key lacks write permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_INSUFFICIENT_SCOPE
              message: insufficient_scope_write_required
            request_id: abc-123
  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