LLM Pulse AI & Agent Traffic API

What AI sends to your site: referral traffic from AI assistants measured by the connected web analytics provider, and AI crawler traffic hitting your origin server. Scale plan and above.

GitHub OpenAPI

Operations 5

GET /metrics/agent_traffic AI bot crawler traffic (Scale plan or above, Beta) #
GET /metrics/ai_traffic AI referral traffic (Scale plan or above) #
GET /web_analytics/schema Web analytics query format (Growth+) #
POST /web_analytics/query Live web analytics query (Growth+) #
GET /dimensions/agent_bots AI bot catalog (Scale plan or above) #

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-ai-agent-traffic-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-ai-agent-traffic-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: LLM Pulse AI & Agent Traffic 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 & Agent Traffic
  description: 'What AI sends to your site: referral traffic from AI assistants measured by the connected web analytics provider, and AI crawler traffic hitting your origin server. Scale plan and above.'
paths:
  /metrics/agent_traffic:
    get:
      tags:
      - AI & Agent Traffic
      summary: AI bot crawler traffic (Scale plan or above, Beta)
      x-llms-description: AI bot crawler traffic by bot/company over time (Scale plan or above, Beta).
      description: Aggregated AI bot traffic hitting the project's origin server (GPTBot, PerplexityBot, ClaudeBot, OAI-SearchBot, Google-Extended, etc.). Sourced from Cloudflare or CSV uploads. Requires the Scale plan; lower tiers receive ERR_PLAN_REQUIRED. A range below 1, or a window whose from is later than its to, returns ERR_INVALID_PARAM.
      operationId: getAgentTraffic
      x-mcp-tool: get_agent_traffic
      x-plan: scale
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Range'
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - name: bot
        in: query
        schema:
          type: string
        description: Filter by bot slug (e.g. gptbot, claudebot, perplexitybot)
      - name: company
        in: query
        schema:
          type: string
        description: Filter by company (e.g. openai, anthropic, google)
      - name: group_by
        in: query
        schema:
          type: string
          enum:
          - bot
          - company
          default: bot
      - $ref: '#/components/parameters/Granularity'
      responses:
        '200':
          description: Agent traffic data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTrafficResponse'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /metrics/ai_traffic:
    get:
      tags:
      - AI & Agent Traffic
      summary: AI referral traffic (Scale plan or above)
      x-llms-description: AI referral traffic (human visits from ChatGPT, Perplexity, Gemini, etc.) by source over time, from the connected web analytics provider (Scale plan or above).
      description: 'AI referral traffic for a project: human visits arriving from AI assistants (ChatGPT, Perplexity, Gemini, Claude, etc.), measured from the connected web analytics provider (Google Analytics 4, Adobe Analytics, PostHog, Plausible, Matomo or Piano). Sessions with a paid medium (such as cpc) are left out on Google Analytics 4 and Piano, the providers that report one. Returns per-source users, sessions and conversions with totals and a conversion rate. Requires a connected provider and the Scale plan; otherwise returns ERR_AI_TRAFFIC_NOT_CONNECTED or ERR_PLAN_REQUIRED. A range below 1, or a window whose from is later than its to, returns ERR_INVALID_PARAM.'
      operationId: getAiTraffic
      x-mcp-tool: get_ai_traffic
      x-mcp-plan: growth
      x-plan: scale
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Range'
      - $ref: '#/components/parameters/From'
      - $ref: '#/components/parameters/To'
      - name: source
        in: query
        schema:
          type: string
        description: Filter by a single AI source slug (e.g. chatgpt, perplexity, gemini, claude)
      - $ref: '#/components/parameters/Granularity'
      responses:
        '200':
          description: AI referral traffic data
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /web_analytics/schema:
    get:
      tags:
      - AI & Agent Traffic
      summary: Web analytics query format (Growth+)
      x-llms-description: 'How to query the connected web analytics provider live: its native query format, enforced rules, an example and its live field list (Growth+).'
      description: 'How to query the web analytics provider connected to the project, live: the provider, the property every query runs on, the native query format it accepts, the allowed top-level fields, the rules the bridge enforces (the connected property is always used, only reads run, row limits), a worked example and, where the provider offers it, its live field list. Cached for an hour. Supported providers: Google Analytics 4, Adobe Analytics or Customer Journey Analytics, Matomo, PostHog, Plausible and Piano, connected on the AI Traffic page. Requires the Growth plan or above; otherwise ERR_PLAN_REQUIRED. Without a connected provider returns ERR_WEB_ANALYTICS_NOT_CONNECTED (404); a provider that refuses the stored credentials returns ERR_WEB_ANALYTICS_ACCESS_REVOKED (403); an unavailable provider, an exhausted provider quota, more than 20 uncached queries a minute or too many running at once for the project returns ERR_WEB_ANALYTICS_UPSTREAM (503): wait for the number of seconds in Retry-After before retrying.'
      operationId: getWebAnalyticsSchema
      x-mcp-tool: get_web_analytics_schema
      x-plan: growth
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Query format for the connected provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebAnalyticsSchemaResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /web_analytics/query:
    post:
      tags:
      - AI & Agent Traffic
      summary: Live web analytics query (Growth+)
      x-llms-description: Live, read-only query in the provider's native format (GA4 runReport, Adobe report, Matomo API, PostHog HogQL, Plausible v2, Piano getData) on the connected property; columns and rows (Growth+).
      description: 'Runs a read-only query, written in the connected provider''s native format, against the project''s property and returns columns and rows: a GA4 Data API runReport body, an Adobe Analytics or Customer Journey Analytics report request, Matomo Reporting API parameters (get methods only), PostHog HogQL, a Plausible Stats API v2 query or a Piano getData body. The connected property, site, report suite or project is always used and any property field in the query is ignored. Rows default to 100 and are capped at 5,000. Identical queries are answered from a 10-minute cache (cached: true). A query the provider rejects returns ERR_WEB_ANALYTICS_INVALID_QUERY (422) with the provider''s own validation message. Each uncached query spends the customer''s provider API quota. A read: no writable key is needed. Supported providers: Google Analytics 4, Adobe Analytics or Customer Journey Analytics, Matomo, PostHog, Plausible and Piano, connected on the AI Traffic page. Requires the Growth plan or above; otherwise ERR_PLAN_REQUIRED. Without a connected provider returns ERR_WEB_ANALYTICS_NOT_CONNECTED (404); a provider that refuses the stored credentials returns ERR_WEB_ANALYTICS_ACCESS_REVOKED (403); an unavailable provider, an exhausted provider quota, more than 20 uncached queries a minute or too many running at once for the project returns ERR_WEB_ANALYTICS_UPSTREAM (503): wait for the number of seconds in Retry-After before retrying.'
      operationId: queryWebAnalytics
      x-mcp-tool: query_web_analytics
      x-plan: growth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_id
              - query
              properties:
                project_id:
                  type: integer
                query:
                  description: 'The query in the provider''s native format (see GET /web_analytics/schema): a JSON object for GA4, Adobe, Matomo, Plausible and Piano; for PostHog, {"query": "<HogQL>"} or the HogQL string. Deliberately untyped so generated clients accept either shape.'
            example:
              project_id: 123
              query:
                dateRanges:
                - startDate: 28daysAgo
                  endDate: yesterday
                dimensions:
                - name: sessionDefaultChannelGroup
                metrics:
                - name: sessions
                - name: keyEvents
                limit: 20
      responses:
        '200':
          description: Query result as columns and rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebAnalyticsQueryResponse'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /dimensions/agent_bots:
    get:
      tags:
      - AI & Agent Traffic
      summary: AI bot catalog (Scale plan or above)
      x-llms-description: Static catalog of AI bots that Agent Analytics can identify (slug, company, category).
      operationId: listAgentBots
      x-mcp-tool: list_agent_bots
      x-plan: scale
      description: Static catalog of AI bots that Agent Analytics can identify. Useful for rendering filter UIs that mirror our internal classification (slug, display name, company, category, Cloudflare verified-bot mapping, description). Requires the Scale plan; lower tiers receive ERR_PLAN_REQUIRED. The equivalent MCP tool list_agent_bots is available on the Scale plan or above.
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
        description: Accepted for compatibility and ignored. The catalog is the same for every project, so any value returns the same list and the project is not checked.
      - $ref: '#/components/parameters/Output'
      responses:
        '200':
          description: Bot catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentBotsResponse'
        '403':
          $ref: '#/components/responses/PlanRequired'
components:
  parameters:
    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.
    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.
    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.
    Granularity:
      name: granularity
      in: query
      schema:
        type: string
        enum:
        - day
        - week
        - month
    From:
      name: from
      in: query
      schema:
        type: string
        format: date-time
    ProjectId:
      name: project_id
      in: query
      required: true
      schema:
        type: integer
      description: Project ID
  schemas:
    WebAnalyticsQueryResponse:
      type: object
      properties:
        project_id:
          type: integer
        provider:
          type: string
          enum:
          - google_analytics
          - adobe_analytics
          - matomo
          - posthog
          - plausible
          - piano
        property:
          type: string
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              kind:
                type: string
                description: dimension or metric, when the provider says.
              type:
                type: string
                description: The provider's column type, when it says (PostHog).
              label:
                type: string
                description: The provider's display label, when it sends one (Piano).
        rows:
          type: array
          items:
            type: array
            items: {}
          description: 'One array per row, values in column order: strings, numbers or null.'
        row_count:
          type: integer
          description: Rows in this response (at most 5,000).
        total_rows:
          type: integer
          description: Rows the provider has for the query, when it reports it.
        truncated:
          type: boolean
          description: True when the provider has more rows than returned; page with its own offset or page field.
        totals:
          type: object
          additionalProperties: true
          description: Metric totals by metric name, when the query asked for them.
        notes:
          type: array
          items:
            type: string
          description: 'Provider caveats: sampling, thresholds, more rows available.'
        meta:
          type: object
          additionalProperties: true
          description: Provider metadata such as GA4 time zone, currency and remaining property quota.
        fetched_at:
          type: string
          format: date-time
          description: When the provider answered.
        cached:
          type: boolean
          description: True when the answer came from the 10-minute cache instead of the provider.
        query:
          type: object
          additionalProperties: true
          description: The request as sent to the provider, with the connected property forced and limits applied.
        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
    AgentTrafficResponse:
      type: object
      properties:
        project_id:
          type: integer
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        group_by:
          type: string
          enum:
          - bot
          - company
        granularity:
          type: string
          enum:
          - day
          - week
          - month
        totals:
          type: object
          additionalProperties:
            type: integer
        timeseries:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: integer
        request_id:
          type: string
    WebAnalyticsSchemaResponse:
      type: object
      properties:
        project_id:
          type: integer
        provider:
          type: string
          enum:
          - google_analytics
          - adobe_analytics
          - matomo
          - posthog
          - plausible
          - piano
          description: The connected web analytics provider.
        property:
          type: string
          description: The property, site, report suite (rsid:...), data view (dataview:...) or project every query runs on.
        query_language:
          type: string
          description: The native query format the provider accepts.
        docs_url:
          type: string
          description: The provider's reference for that format.
        allowed_fields:
          type: array
          items:
            type: string
          description: Top-level query fields that are forwarded.
        rules:
          type: array
          items:
            type: string
          description: What the bridge enforces and the provider's main constraints.
        example:
          type: object
          additionalProperties: true
          description: A worked query to adapt.
        fields:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: 'The provider''s live field list where it offers one: GA4 dimensions and metrics with custom definitions, Adobe ids, Matomo report methods, PostHog event names, the Plausible catalog. Null when the provider did not return it.'
        fields_unavailable:
          type: string
          description: Present when the field list could not be read; the format and example still apply.
        request_id:
          type: string
    AgentBot:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        company:
          type: string
        category:
          type: string
        cf_verified_category:
          type: string
        description:
          type: string
    AgentBotsResponse:
      type: object
      properties:
        bots:
          type: array
          items:
            $ref: '#/components/schemas/AgentBot'
        companies:
          type: array
          items:
            type: string
        request_id:
          type: string
  responses:
    ServiceUnavailable:
      description: 'Upstream provider unavailable, retry after the number of seconds in the Retry-After header: Google''s own value when it sent one, otherwise 900 after a quota error and 60 after an outage'
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_SEARCH_CONSOLE_UPSTREAM
              message: Google Search Console is temporarily unavailable. Retry in a few minutes.
            request_id: abc-123
    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
    Forbidden:
      description: Access forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_REVOKED_API_KEY
              message: revoked_api_key
            request_id: abc-123
    PlanRequired:
      description: Endpoint requires a higher plan tier
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_PLAN_REQUIRED
              message: Scale plan or above required
            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
  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