> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trywildcard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Page Traffic

> Page loads per page for people and AI agents, including anonymous visitors

See [Page traffic: people and AI agents](https://docs.trywildcard.ai/partners.md#page-traffic-people-and-ai-agents)
for how human and AI sources are counted and what the coverage limits are.


## OpenAPI

````yaml GET /v1/traffic/pages
openapi: 3.0.3
info:
  title: Wildcard API
  description: >
    Programmatic access to your Wildcard data — identified website visitors,

    companies, events, and analytics.


    ## Authentication

    Visitor-data endpoints require an `mk_live_...` data key in `X-API-Key`.

    Partner management endpoints under `/v1/partner/*` require your
    `pk_live_...`

    management key instead. `/v1/health` is public and requires no key.


    ```bash

    curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people

    ```


    ## Data API Rate Limiting

    - **1,000 requests per hour** per customer (shared across all API keys)

    - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

    - When exceeded, you'll receive a `429` response with a `Retry-After` header


    ## Pagination

    List endpoints use cursor-based pagination. Pass the `nextCursor` from the
    response

    as the `cursor` query parameter to fetch the next page.


    ## Sorting

    Visitor lists are sorted by most recently seen first (`lastSeen`
    descending).

    Traffic pages sort by observed human and AI page views, then domain and
    path.

    Custom sorting is not yet supported — passing a `sort` or `order` query

    parameter returns `400 bad_request`. Custom sorting options will be
    available

    in a future version.
  version: 1.1.0
  contact:
    name: Wildcard Support
    email: support@trywildcard.ai
    url: https://trywildcard.ai
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Traffic
    description: >-
      Per-page human and AI traffic, including anonymous activity and server
      collection
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/traffic/pages:
    get:
      tags:
        - Traffic
      summary: Page traffic for humans and AI agents
      description: |
        Counts observed page loads including anonymous human visitors. Defaults
        to browser human activity and server AI observations; these sources are
        never added together. Requires server collection for non-JavaScript AI
        crawlers. Agent labels are User-Agent claims, not verified identities.
        Exact domain, domain group, client reference and key scopes intersect.
        A successful response is complete for the bounded stored observations;
        oversized requests return 422 without partial totals. Collection gaps,
        browser blockers and retention can still limit observed traffic.
      parameters:
        - name: since
          in: query
          schema:
            type: string
            format: date-time
          description: Inclusive start; default seven days before until
        - name: until
          in: query
          schema:
            type: string
            format: date-time
          description: Exclusive end; default now. Maximum window 31 days
        - name: domain
          in: query
          schema:
            type: string
          description: Exact hostname; does not widen to child or sibling sites
        - $ref: '#/components/parameters/client_ref'
        - $ref: '#/components/parameters/domain_group_id'
        - name: path
          in: query
          schema:
            type: string
          description: Exact page path; no query or fragment
        - name: agent
          in: query
          schema:
            type: string
          description: Return only server AI traffic matching this returned agent ID
        - name: human_source
          in: query
          schema:
            type: string
            enum:
              - browser
              - server
            default: browser
        - name: include_people
          in: query
          schema:
            type: boolean
            default: false
          description: >-
            Match explicit browser identities to currently visible people;
            maximum 100 distinct emails per request
        - name: measure
          in: query
          schema:
            type: string
            enum:
              - all
              - human
              - ai
            default: all
          description: >-
            human reads only human observations and omits ai fields; ai reads
            only server observations and omits human fields and
            identifiedPeople. Fields for the unrequested part are omitted, not
            zeroed
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: cursor
          in: query
          schema:
            type: string
          description: >-
            Reuse all filters; pins the time window. Batches requested within
            five minutes usually reuse the first batch's result; otherwise late
            arriving data can change results
      responses:
        '200':
          description: Per-page traffic and totals across all matching pages
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - totals
                  - pagination
                  - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrafficPage'
                  totals:
                    type: object
                    properties:
                      human:
                        $ref: '#/components/schemas/TrafficCounts'
                      ai:
                        $ref: '#/components/schemas/AgentTraffic'
                  pagination:
                    type: object
                    properties:
                      nextCursor:
                        type: string
                        nullable: true
                      totalPages:
                        type: integer
                        description: >-
                          Total number of matching page URLs, not pagination
                          batches
                  meta:
                    type: object
                    properties:
                      since:
                        type: string
                        format: date-time
                      until:
                        type: string
                        format: date-time
                      complete:
                        type: boolean
                        enum:
                          - true
                      measure:
                        type: string
                        enum:
                          - all
                          - human
                          - ai
                      humanSource:
                        type: string
                        enum:
                          - browser
                          - server
                      aiSource:
                        type: string
                        enum:
                          - server
                      classification:
                        type: string
                        enum:
                          - user_agent_claim
                      operatorVerified:
                        type: boolean
                        enum:
                          - false
                      identityMethod:
                        type: string
                        nullable: true
                      generatedAt:
                        type: string
                        format: date-time
                      aiCoverage:
                        type: string
                        enum:
                          - server_observations_received
                          - server_collection_not_observed
                      coverage:
                        type: object
                        description: >-
                          Browser and server observed page views and
                          lastObservedAt timestamps before the agent filter
                        additionalProperties:
                          type: object
                          properties:
                            pageViews:
                              type: integer
                            pageRequests:
                              type: integer
                            lastObservedAt:
                              type: string
                              format: date-time
                              nullable: true
        '400':
          description: Invalid parameter or cursor
        '401':
          description: Invalid data key or account unavailable
        '403':
          description: Scope unavailable
        '404':
          description: Domain group not found
        '422':
          description: >-
            Narrow the window; scan or identity budget exceeded. No partial
            totals returned
        '429':
          description: Data API rate limit reached
        '503':
          description: >-
            Query processing timed out, data changed, or deletion protection
            temporarily unavailable; retry
components:
  parameters:
    client_ref:
      name: client_ref
      in: query
      schema:
        type: string
      description: >
        Partner accounts only. Restrict results to one client by the reference
        label set on its tracked domains. Case-insensitive. If a client has
        several domains registered, all of them are included.
      example: ACME-1
    domain_group_id:
      name: domain_group_id
      in: query
      schema:
        type: string
        pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$
      description: >
        Partner domain group ID. Matches exact member hostnames (www aliases
        normalized), including any member site the person has visited.
        Intersects domain, client_ref, and the key's scope; never grants extra
        access. Empty group returns zero matches; missing/foreign group returns
        404; invalid ID returns 400. Keep this filter when following pagination
        cursors.
      example: acme
  schemas:
    TrafficPage:
      type: object
      required:
        - domain
        - path
      description: >-
        human and ai are always present with the default measure=all;
        measure=human omits ai and measure=ai omits human
      properties:
        domain:
          type: string
          example: letter.company
        path:
          type: string
          example: /pricing
        human:
          $ref: '#/components/schemas/TrafficCounts'
        ai:
          $ref: '#/components/schemas/AgentTraffic'
        browserAiPageViews:
          type: integer
          description: Browser AI observations kept separate from server AI totals
        browserOtherBotPageViews:
          type: integer
        serverOtherBotPageViews:
          type: integer
        browserUnclassifiedPageViews:
          type: integer
        serverUnclassifiedPageViews:
          type: integer
        serverPageRequests:
          type: integer
          description: All server page requests before traffic classification
        identifiedPeople:
          type: array
          description: >-
            Conservative explicit browser identity matches; present with
            include_people=true
          items:
            type: object
            properties:
              id:
                type: string
              firstName:
                type: string
                nullable: true
              lastName:
                type: string
                nullable: true
              company:
                type: string
                nullable: true
    TrafficCounts:
      type: object
      required:
        - pageViews
        - uniqueVisitors
        - sessions
        - pageViewsWithoutVisitorId
        - pageViewsWithoutSessionId
      properties:
        pageViews:
          type: integer
          minimum: 0
        uniqueVisitors:
          type: integer
          minimum: 0
          description: Distinct recorded visitor IDs, scoped by hostname
        sessions:
          type: integer
          minimum: 0
          description: Distinct recorded session IDs, scoped by hostname
        pageViewsWithoutVisitorId:
          type: integer
          minimum: 0
        pageViewsWithoutSessionId:
          type: integer
          minimum: 0
        identifiedPageViews:
          type: integer
          minimum: 0
          description: Present with include_people=true
        unidentifiedPageViews:
          type: integer
          minimum: 0
          description: Present with include_people=true
    AgentTraffic:
      type: object
      required:
        - requests
        - pageViews
        - byAgent
      properties:
        requests:
          type: integer
          minimum: 0
          description: Observed AI page requests
        pageViews:
          type: integer
          minimum: 0
          description: Subset with a confirmed successful HTML response
        byAgent:
          type: array
          items:
            type: object
            required:
              - agent
              - operator
              - requests
              - pageViews
            properties:
              agent:
                type: string
                example: openai-crawler
              operator:
                type: string
                example: openai
              requests:
                type: integer
                minimum: 0
              pageViews:
                type: integer
                minimum: 0
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.