> ## 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.

# List Person Events

> Returns the full journey — every tracked event for a specific person



## OpenAPI

````yaml GET /v1/people/{id}/events
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/people/{id}/events:
    get:
      tags:
        - Events
      summary: List person events
      description: >
        Returns the full journey for a person — every tracked behavioural event,

        sorted most recent first.


        Journeys vary enormously: one visitor may have three events, another

        several thousand, and the mix of event types differs every time. Page

        through with `cursor` rather than assuming a bounded length, and treat

        each event's fields as open-ended (see the Event schema).


        **Partner accounts:** each event carries the `domain` and `clientRef`

        identifying which client's site it happened on. Narrow to one client

        with `domain`, `client_ref`, or `domain_group_id`. Group filtering
        applies

        to each event's site. A domain-scoped API key is restricted to

        its own client automatically — for such a key, a person with no events

        in scope returns 404.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Person ID
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - name: event_type
          in: query
          schema:
            type: string
          description: >
            Return only events of this type. Accepts any string, including event
            types introduced after this document was written.
          example: click
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/client_ref'
        - $ref: '#/components/parameters/domain_group_id'
      responses:
        '200':
          description: List of events
          content:
            application/json:
              schema:
                type: object
                properties:
                  person:
                    type: object
                    description: Summary of the person these events belong to
                    properties:
                      id:
                        type: string
                      firstName:
                        type: string
                        nullable: true
                      lastName:
                        type: string
                        nullable: true
                      email:
                        type: string
                        nullable: true
                      company:
                        type: string
                        nullable: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '404':
          description: Person not found
components:
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
      description: Number of records per page
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from the previous response's `nextCursor`
    domain:
      name: domain
      in: query
      schema:
        type: string
      description: >
        Partner accounts only. Restrict results to one tracked client domain.
        Matches subdomains too, so `acme.com` includes `app.acme.com`. A
        domain-scoped API key cannot use this to reach beyond its own scope.
      example: acme.com
    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:
    Event:
      type: object
      description: >
        A single step in a visitor's journey. The shape is OPEN-ENDED: no two
        journeys are alike, and detail fields vary by event type and grow over
        time. eventId, sessionId, eventType, timestamp and url are always
        present; treat everything else as optional and ignore unknown fields
        rather than failing on them.
      additionalProperties: true
      properties:
        eventId:
          type: string
        sessionId:
          type: string
        eventType:
          type: string
          description: >
            The type of behavioral event. NOT a closed set — new event types are
            added as the tracking pixel evolves, and appear here without any API
            version change. Do not reject unrecognised values. Common types
            today include page_view, click, scroll_depth, video_play,
            video_pause, video_complete, exit_intent, form_submission, copy and
            file_download.
        timestamp:
          type: string
          format: date-time
        url:
          type: string
        pageTitle:
          type: string
          nullable: true
        domain:
          type: string
          nullable: true
          description: >
            Domain the event occurred on, derived from the event URL. For
            partner accounts this identifies which client's site the visitor was
            on, and is the value domain/client_ref filtering and key scoping
            match against.
        clientRef:
          type: string
          nullable: true
          description: >
            The partner's own label for the client that owns this event, as set
            on the tracked domain. Empty when the domain has no reference set.
        clickElement:
          type: string
          nullable: true
          description: Present on click events
        clickHref:
          type: string
          nullable: true
          description: Present on click events
        clickX:
          type: integer
          nullable: true
          description: Horizontal click coordinate, present on click events
        clickY:
          type: integer
          nullable: true
          description: Vertical click coordinate, present on click events
        scrollPercentage:
          type: integer
          nullable: true
          description: Present on scroll_depth events
        scrollThreshold:
          type: integer
          nullable: true
          description: Scroll threshold that fired, present on scroll_depth events
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Requested page size
        count:
          type: integer
          description: Number of items in this page
        nextCursor:
          type: string
          nullable: true
          description: Pass this as `cursor` to get the next page. Null when no more pages.
  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.