LLM Pulse Custom Reports API

The custom reports built under Reports > Custom Reports: list them, read one with the data of every widget as its page shows it, and email it to its recipients now. Scale plan and above.

GitHub OpenAPI

Operations 3

GET /custom_reports List custom reports #
GET /custom_reports/{id} Get a custom report with its widget data #
POST /custom_reports/{id}/send Send a custom report now #

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-custom-reports-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-custom-reports-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: LLM Pulse Custom Reports 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: Custom Reports
  description: 'The custom reports built under Reports > Custom Reports: list them, read one with the data of every widget as its page shows it, and email it to its recipients now. Scale plan and above.'
paths:
  /custom_reports:
    get:
      tags:
      - Custom Reports
      summary: List custom reports
      x-llms-description: List a project's custom reports with their date range, delivery schedule, recipient count, shared-link state and widgets.
      operationId: listCustomReports
      x-mcp-tool: list_custom_reports
      x-plan: scale
      description: The custom reports of the project, newest first, as the Reports > Custom Reports list shows them. Recipient addresses, the shared-link token and the password are never returned. Requires the Scale plan or above.
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Output'
      responses:
        '200':
          description: Paginated custom reports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportsResponse'
        '403':
          $ref: '#/components/responses/PlanRequired'
  /custom_reports/{id}:
    get:
      tags:
      - Custom Reports
      summary: Get a custom report with its widget data
      x-llms-description: One custom report's configuration and the data of every widget, computed as its page shows it now (read-only).
      operationId: getCustomReport
      x-mcp-tool: get_custom_report
      x-plan: scale
      description: 'The configuration of one custom report (date range, filters, schedule, layout) and the data of every widget computed for today, the same numbers the report page, its shared link and its PDF show. Each widget carries its `kind` and a `data` object shaped by it: `series` for `timeseries`, `slices` for `donut`, `bars` for `bar`, `values` and `changes` for `kpi_grid`, `rows` for `table`. A widget whose data source is not connected has `available: false` and `data: null`. Nothing is saved or sent. Requires the Scale plan or above.'
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Custom report id, from GET /custom_reports
      responses:
        '200':
          description: Report configuration and widget data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportDetailResponse'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          $ref: '#/components/responses/NotFound'
  /custom_reports/{id}/send:
    post:
      tags:
      - Custom Reports
      summary: Send a custom report now
      x-llms-description: Email a custom report to its recipients now, like the report page's Send now button (published reports with recipients, once every 10 minutes).
      operationId: sendCustomReport
      x-mcp-tool: send_custom_report
      x-plan: scale
      x-write: true
      description: 'Queues the report''s PDF for its recipients, like the Send now button on the report page: the report must be published and have at least one recipient (ERR_INVALID_PARAM otherwise), and each report can be sent once every 10 minutes (429 ERR_RATE_LIMITED with Retry-After). Not available from a white-label portal or for a report made inside one (ERR_INTEGRATION_UNAVAILABLE). Requires the Scale plan or above, a `read_write` scope API key and, for team members, update permission on Custom Reports.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Custom report id, from GET /custom_reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - project_id
              properties:
                project_id:
                  type: integer
      responses:
        '202':
          description: The report is queued for its recipients
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportSendResponse'
        '403':
          $ref: '#/components/responses/PortalWriteForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/ReportSendCooldown'
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.
    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
    ProjectId:
      name: project_id
      in: query
      required: true
      schema:
        type: integer
      description: Project ID
  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
    PortalWriteForbidden:
      description: Writes with a read-only key answer ERR_INSUFFICIENT_SCOPE, a team member without the permission ERR_INSUFFICIENT_PERMISSION, and a request made on a white-label portal host, where the app does not offer this action, ERR_INTEGRATION_UNAVAILABLE, with the same status
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_INSUFFICIENT_SCOPE
              message: insufficient_scope_write_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
    ReportSendCooldown:
      description: The report was sent less than 10 minutes ago; retry after the number of seconds in the Retry-After header
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ERR_RATE_LIMITED
              message: This report was just sent; try again in 540 seconds
            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
  schemas:
    CustomReportDateRange:
      type: object
      required:
      - type
      - range_days
      - custom_from
      - custom_to
      properties:
        type:
          type: string
          enum:
          - rolling
          - previous_month
          - previous_3_months
          - custom
          description: rolling (the last range_days days), previous_month (the previous calendar month), previous_3_months (the 3 calendar months before the current one) or custom (fixed dates, custom_from to custom_to)
        range_days:
          type:
          - integer
          - 'null'
          description: Length of a rolling window; null for the other types
        custom_from:
          type:
          - string
          - 'null'
          format: date
          description: First day chosen for a custom range; null for the other types
        custom_to:
          type:
          - string
          - 'null'
          format: date
          description: Last day chosen for a custom range, which can be after today; null for the other types
        from:
          type: string
          format: date
          description: First day of the window as of now (detail only)
        to:
          type: string
          format: date
          description: Last day of the window as of now (detail only); a custom range stops at today
        label:
          type: string
          description: The window as the report shows it (detail only)
    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
    CustomReportWidget:
      type: object
      required:
      - key
      - label
      - kind
      - width
      - available
      properties:
        key:
          type: string
        label:
          type: string
        kind:
          type: string
          enum:
          - kpi_grid
          - timeseries
          - donut
          - bar
          - table
        width:
          type: string
          enum:
          - half
          - full
        available:
          type: boolean
          description: false when the widget's data source (web analytics, agent analytics, owned media) is not connected
        data:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: 'Shaped by kind. timeseries: series [{ name, color, points [{ date, value }] }]. donut: slices [{ name, value, color }]. bar: bars [{ label, value, color }]. kpi_grid: values and changes (null unless the report compares with the previous period). table: rows, one object per row; the monthly_breakdown widget has one row per calendar month of the window with month, from, to, partial (a month the window cuts), responses, mentions, visibility, weighted_visibility, sov_share, citations and avg_mention_position. Null when the widget is not available.'
    CustomReportDetailResponse:
      type: object
      required:
      - project_id
      - id
      - name
      - date_range
      - schedule
      - filters
      - blocks
      - widgets
      - generated_at
      - request_id
      properties:
        project_id:
          type: integer
        id:
          type: integer
        name:
          type: string
        date_range:
          $ref: '#/components/schemas/CustomReportDateRange'
        schedule:
          $ref: '#/components/schemas/CustomReportSchedule'
        recipients_count:
          type: integer
        published:
          type: boolean
        public_link_active:
          type: boolean
        password_protected:
          type: boolean
        portal_only:
          type: boolean
        last_sent_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the report was last emailed, on its schedule or with Send now
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        filters:
          $ref: '#/components/schemas/CustomReportFilters'
        compare_previous:
          type: boolean
        attach_excel:
          type: boolean
        manual_send_available_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the 10-minute cooldown after the last manual send ends; null when none is running
        generated_at:
          type: string
          format: date-time
        blocks:
          type: array
          items:
            $ref: '#/components/schemas/CustomReportBlock'
          description: The report layout in order
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/CustomReportWidget'
        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
    CustomReportFilters:
      type: object
      required:
      - models
      - collection_ids
      - competitor_ids
      properties:
        models:
          type: array
          items:
            type: string
          description: AI models the report covers; empty means every enabled model
        collection_ids:
          type: array
          items:
            type: integer
          description: Tags the report is limited to; empty means every prompt
        brand_kind:
          type:
          - string
          - 'null'
        competitor_ids:
          type: array
          items:
            type: integer
          description: Competitors compared, the report's own choice or else the Overview selection
    CustomReportWidgetRef:
      type: object
      required:
      - key
      - label
      - kind
      properties:
        key:
          type: string
        label:
          type: string
        kind:
          type: string
          enum:
          - kpi_grid
          - timeseries
          - donut
          - bar
          - table
    CustomReportsResponse:
      allOf:
      - $ref: '#/components/schemas/PaginatedEnvelope'
      - type: object
        required:
        - data
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/CustomReportSummary'
    CustomReportSummary:
      type: object
      required:
      - id
      - name
      - date_range
      - schedule
      - recipients_count
      - published
      - public_link_active
      - password_protected
      - portal_only
      - widget_count
      - widgets
      - created_at
      - updated_at
      properties:
        id:
          type: integer
        name:
          type: string
        date_range:
          $ref: '#/components/schemas/CustomReportDateRange'
        schedule:
          $ref: '#/components/schemas/CustomReportSchedule'
        recipients_count:
          type: integer
        published:
          type: boolean
          description: Whether the shared link is published
        public_link_active:
          type: boolean
          description: Whether the shared link opens (published, not made inside a client portal, and the account is active on the Scale tier or higher)
        password_protected:
          type: boolean
        portal_only:
          type: boolean
          description: Made inside a client portal, so it cannot be shared or emailed
        widget_count:
          type: integer
        widgets:
          type: array
          items:
            $ref: '#/components/schemas/CustomReportWidgetRef'
        last_sent_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the report was last emailed, on its schedule or with Send now
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CustomReportSchedule:
      type: object
      required:
      - enabled
      properties:
        enabled:
          type: boolean
        day_of_week:
          type:
          - integer
          - 'null'
          description: 0 (Sunday) to 6 (Saturday)
        hour:
          type:
          - integer
          - 'null'
        timezone:
          type:
          - string
          - 'null'
    CustomReportBlock:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - widget
          - heading
          - text
          - separator
          - image
        key:
          type:
          - string
          - 'null'
          description: The widget key, for a widget block
        text:
          type:
          - string
          - 'null'
          description: The text of a heading or text block
    CustomReportSendResponse:
      type: object
      required:
      - project_id
      - id
      - status
      - recipients_count
      - request_id
      properties:
        project_id:
          type: integer
        id:
          type: integer
        status:
          type: string
          enum:
          - queued
        recipients_count:
          type: integer
        request_id:
          type: string
  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