Iterant Public: Reports API

The Public: Reports API from Iterant — 1 operation(s) for public: reports.

GitHub OpenAPI

Operations 1

GET /api/v1/public/brands/{brandSlug}/reports/pages/ Get a page (or brand-wide) report #

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/iterant-ai:iterant-ai-public-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. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

iterant-ai-public-reports-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: 'Iterant Public Public: Reports API'
  version: 1.0.0
  description: 'The Iterant public API: read a brand''s pages, page opportunities, reports and AI visibility, and start Iterant''s agent on a page. Guides: https://iterant.ai/docs/developers/rest-api


    **Authentication.** Send `Authorization: Bearer itr_...`, an API key an organization admin mints at Settings > Developers.


    **Rate limits.** 600 requests per minute per key, and 30 task starts per minute. Responses carry the IETF `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` fields. A `429` carries `Retry-After` in seconds. Requests without a valid key are limited to 60 per minute per client IP.


    **Idempotency.** `POST .../tasks/` takes an `Idempotency-Key` header. For 24 hours, a retry with the same key and body returns the first task instead of starting a second.


    **Versioning and deprecation.** The version is in the path: `/api/v1/`. Breaking changes ship under a new version. A deprecated version keeps working for at least 6 months after the announcement, and its responses carry `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594). Nothing is deprecated today. Policy: https://iterant.ai/docs/developers/rest-api#versioning-and-deprecation'
servers:
- url: https://api.iterant.ai
  description: Production server
tags:
- name: 'Public: Reports'
paths:
  /api/v1/public/brands/{brandSlug}/reports/pages/:
    get:
      operationId: publicPageReport
      description: 'How a page is performing, projected to the `metrics` you ask for. Each one is a separate upstream read, so ask for what you need:


        - `performance`: Search Console clicks/impressions/CTR/position

        - `traffic`: visitor sessions and conversions from the signals mart

        - `conversions`: per-definition conversion counts

        - `anatomy`: which components get clicked and how far visitors scroll


        Every performance block carries a `state`: only `ok` means the numbers are real. `no_data`, `unconfigured` and `error` return null metrics. Report the state, never substitute zero.


        `traffic`, `conversions` and `anatomy` are sampling-weighted estimates and honour `window`. `performance` is snapshot-shaped: it reports the window the capture covered, which `window` does not change. Omit `urlPath` for a brand-wide roll-up.


        A localized route (`/es/pricing`) reports on its page, the same as the page''s own route: `scope.urlPath` names the page, and `traffic` and `anatomy` count the visits to every route the page serves at, in every language.'
      summary: Get a page (or brand-wide) report
      parameters:
      - in: path
        name: brandSlug
        schema:
          type: string
        required: true
      - in: query
        name: metrics
        schema:
          type: string
        description: 'Comma-separated projections. Legal values: performance, traffic, conversions, anatomy. Defaults to performance.'
      - in: query
        name: responseFormat
        schema:
          type: string
          enum:
          - concise
          - detailed
          default: concise
        description: 'How much to return. `concise` (the default) omits long-form text: briefs, outlines, evidence, passage excerpts, per-dimension breakdowns. `detailed` includes it and costs several times the tokens.'
      - in: query
        name: urlPath
        schema:
          type: string
        description: Page route, localized or not. Omit for a brand-wide roll-up.
      - in: query
        name: window
        schema:
          type: string
          enum:
          - 28d
          - 7d
          - 90d
          default: 28d
        description: Rolling window ending today.
      tags:
      - 'Public: Reports'
      security:
      - tenantApiKeyAuth: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPageReportErrorResponse400'
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
              examples:
                AuthenticationFailed:
                  value:
                    type: client_error
                    errors:
                    - code: authentication_failed
                      detail: Incorrect authentication credentials.
                      attr: null
                NotAuthenticated:
                  value:
                    type: client_error
                    errors:
                    - code: not_authenticated
                      detail: Authentication credentials were not provided.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse405'
              examples:
                MethodNotAllowed:
                  value:
                    type: client_error
                    errors:
                    - code: method_not_allowed
                      detail: Method "get" not allowed.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse406'
              examples:
                NotAcceptable:
                  value:
                    type: client_error
                    errors:
                    - code: not_acceptable
                      detail: Could not satisfy the request Accept header.
                      attr: null
          description: ''
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse415'
              examples:
                UnsupportedMediaType:
                  value:
                    type: client_error
                    errors:
                    - code: unsupported_media_type
                      detail: Unsupported media type "application/json" in request.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse429'
              examples:
                Throttled:
                  value:
                    type: client_error
                    errors:
                    - code: throttled
                      detail: Request was throttled.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
              examples:
                APIException:
                  value:
                    type: server_error
                    errors:
                    - code: error
                      detail: A server error occurred.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPageReport'
              examples:
                PerformanceFor/pricing,SearchConsoleNotConnected:
                  value:
                    brandSlug: orbital-labs
                    scope:
                      urlPath: /pricing
                    window: 28d
                    performance:
                      search:
                        state: unconfigured
                        windowDays: null
                        effectiveThrough: null
                        metrics: null
                  summary: Performance for /pricing, Search Console not connected
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
components:
  schemas:
    ParseErrorCodeEnum:
      enum:
      - parse_error
      type: string
      description: '* `parse_error` - Parse Error'
    ErrorCode404Enum:
      enum:
      - not_found
      type: string
      description: '* `not_found` - Not Found'
    Error405:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode405Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    Error406:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode406Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ParseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ParseErrorCodeEnum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    PublicPageReport:
      type: object
      description: A page (or brand-wide) report, projected to the requested `metrics`.
      properties:
        brandSlug:
          type: string
        scope:
          type: object
          additionalProperties: {}
        window:
          type: string
        performance:
          $ref: '#/components/schemas/PublicPerformance'
        traffic:
          $ref: '#/components/schemas/PublicSourceBlock'
        conversions:
          $ref: '#/components/schemas/PublicConversions'
        anatomy:
          $ref: '#/components/schemas/PublicAnatomy'
      required:
      - brandSlug
      - scope
      - window
    ErrorCode415Enum:
      enum:
      - unsupported_media_type
      type: string
      description: '* `unsupported_media_type` - Unsupported Media Type'
    ParseErrorResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ParseError'
      required:
      - errors
      - type
    PublicConversions:
      type: object
      properties:
        isExact:
          type: boolean
          description: False means a sampled mart estimate; true means an exact Postgres form-submission count.
        scope:
          type: string
          description: 'Always ''brand'': conversion definitions carry no page dimension in the mart.'
        definitions:
          type: array
          items:
            $ref: '#/components/schemas/PublicConversionDefinition'
      required:
      - definitions
      - isExact
      - scope
    ErrorResponse405:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error405'
      required:
      - errors
      - type
    ErrorResponse429:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error429'
      required:
      - errors
      - type
    Error500:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode500Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    Error415:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode415Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ServerErrorEnum:
      enum:
      - server_error
      type: string
      description: '* `server_error` - Server Error'
    ErrorResponse404:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error404'
      required:
      - errors
      - type
    ErrorCode406Enum:
      enum:
      - not_acceptable
      type: string
      description: '* `not_acceptable` - Not Acceptable'
    ErrorCode405Enum:
      enum:
      - method_not_allowed
      type: string
      description: '* `method_not_allowed` - Method Not Allowed'
    PublicSourceBlock:
      type: object
      description: 'A metric block plus the state that produced it.


        ``state`` is load-bearing: metrics are null whenever it is not ``ok``, and a

        consumer that reads that as zero is wrong rather than approximately right.'
      properties:
        state:
          type: string
          description: 'One of: ok, no_data, unconfigured, error.'
        windowDays:
          type:
          - integer
          - 'null'
        effectiveThrough:
          type:
          - string
          - 'null'
          format: date
        metrics:
          type:
          - object
          - 'null'
          additionalProperties: {}
      required:
      - effectiveThrough
      - metrics
      - state
      - windowDays
    ErrorResponse415:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error415'
      required:
      - errors
      - type
    Error404:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode404Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    PublicPerformance:
      type: object
      properties:
        search:
          $ref: '#/components/schemas/PublicSourceBlock'
      required:
      - search
    ErrorResponse401:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error401'
      required:
      - errors
      - type
    ErrorResponse406:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error406'
      required:
      - errors
      - type
    ErrorResponse500:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ServerErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error500'
      required:
      - errors
      - type
    PublicPageReportErrorResponse400:
      oneOf:
      - $ref: '#/components/schemas/ParseErrorResponse'
      discriminator:
        propertyName: type
        mapping:
          client_error: '#/components/schemas/ParseErrorResponse'
    Error429:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode429Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ErrorCode401Enum:
      enum:
      - authentication_failed
      - not_authenticated
      type: string
      description: '* `authentication_failed` - Authentication Failed

        * `not_authenticated` - Not Authenticated'
    PublicAnatomy:
      type: object
      properties:
        estimated:
          type: boolean
        pageLeaves:
          type: integer
        avgPeakScrollPct:
          type:
          - number
          - 'null'
          format: double
        topComponents:
          type: array
          items:
            $ref: '#/components/schemas/PublicPageComponent'
      required:
      - avgPeakScrollPct
      - estimated
      - pageLeaves
      - topComponents
    PublicConversionDefinition:
      type: object
      properties:
        name:
          type: string
        event:
          type: string
        count:
          type: integer
      required:
      - count
      - event
      - name
    ErrorCode429Enum:
      enum:
      - throttled
      type: string
      description: '* `throttled` - Throttled'
    ErrorCode500Enum:
      enum:
      - error
      type: string
      description: '* `error` - Error'
    PublicPageComponent:
      type: object
      properties:
        componentId:
          type: string
        clicks:
          type: integer
      required:
      - clicks
      - componentId
    ClientErrorEnum:
      enum:
      - client_error
      type: string
      description: '* `client_error` - Client Error'
    Error401:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode401Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
  headers:
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the budget has room again.
      schema:
        type: integer
    RateLimit-Limit:
      description: Requests allowed per window, for the tightest budget this request drew on.
      schema:
        type: integer
    RateLimit-Policy:
      description: The budget as `<limit>;w=<window seconds>`, e.g. `600;w=60`.
      schema:
        type: string
  securitySchemes:
    tenantApiKeyAuth:
      type: http
      scheme: bearer