---
title: "List a contact's activity"
method: GET
path: "/contacts/{id}/events"
tags: ["Contacts"]
---

# List a contact's activity

`GET /contacts/{id}/events`

## Request

- Base URL: `https://api.privy.com/v1`
- URL: `https://api.privy.com/v1/contacts/{id}/events`
- Auth: HTTP bearer

Retrieve the contact's activity timeline — signups, email and SMS sends, opens and clicks,
orders, checkouts, tag changes — newest first. This is the same record the Privy dashboard's
contact page shows, so "why did this contact get X?" can be answered from the API alone:
find the send, the signup that triggered it, and the display or campaign each traces to.

Each entry names its `type` (the event vocabulary below, as stored), when it happened, the
display or campaign it belongs to (when the event carries one, even one since deleted), and the
event's raw `properties`, whose shape varies by type (the recipient IP and user agent recorded
on email opens and clicks, and the IP-derived location on signups, are not included).

By default the timeline covers the last 24 months; narrow it with `occurred_after` /
`occurred_before` (both bounds exclusive; a bare date means midnight at the start of that
day) or to one event type with `type`.

**Required scope:** `contacts_read`

## Path parameters

- `id` string, required

## Query parameters

- `type` string
- `occurred_after` string
- `occurred_before` string
- `page` integer
- `per_page` integer

## Headers

- `Privy-Account-Id` string

## Response `200`

A paginated list of the contact's events, newest first.

- object
  - `data` ContactEvent[]
    - `type` string: The event name as stored. The `type` filter lists the common values; other stored names (e.g. `email-bounced`, `text-clicked`) appear as well and filter the same way.
    - `occurred_at` string, date-time
    - `campaign` object, nullable: The display or message campaign the event belongs to; `null` when the event carries none (e.g. a store order or a tag change). `display` ids round-trip through `GET /v1/displays/{id}`; `newsletter` and `flow` ids through `GET /v1/campaigns/{id}` — unless the campaign has since been deleted: it still names itself here but no longer resolves there. `workflow` is the legacy automation type, which that read does not serve.
      - `id` string
      - `title` string
      - `type` 'display' | 'newsletter' | 'flow' | 'workflow'
    - `properties` object: The raw event payload. Shape varies by `type`. The recipient `ip` and `useragent` stamped on email opens and clicks are omitted. A signup's `browsing_data` carries only the page, referrer, and utm attribution the widget recorded; the IP-derived location is omitted. SMS send events carry the `message_body` that was sent.
  - `note` string: Present only when the account's plan limits the timeline to signup events.
  - `pagination` PaginationEnvelope
    - `page` integer
    - `per_page` integer
    - `total_count` integer
    - `total_pages` integer

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `404`: The requested resource does not exist or does not belong to your account.
- `422`: One or more fields failed validation.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `cf0885e90d5a`: 10 warning
  - added the new `forbidden` enum value to the `error/code` response property for the response status `401`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `403`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `404`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `422`
  - …6 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/contacts/:id/events/get.md)

---

[API](https://skmtc.dev/privy/apis/privy-api.md) - [All operations](https://skmtc.dev/privy/apis/privy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/privy/apis/privy-api/revisions/bc29b48dcdd2?raw)