# Event history

> List event metadata and retrieve available exact webhook payload bytes for an team or project.

The Platform API records a bounded history of team and project events.
Use it to inspect what happened before checking the related webhook deliveries.
History, webhooks, event streams, `polymorfa listen`, and the MCP event tools
contain only the event types documented in the [webhook reference](https://docs.polymorfa.com/development/webhooks),
plus test events you create.

Team events include customer lifecycle and campaign lifecycle activity:

```http
GET /platform/events
GET /platform/events/{eventId}
```

Project events cover activity owned by one project:

```http
GET /platform/projects/{projectId}/events
GET /platform/projects/{projectId}/events/{eventId}
```

All four routes require `events:read`. Project credentials can access only the
project routes for their bound project. Team credentials use the
team routes directly and can select a project through the project
route prefix.

## List events

List routes return newest events first. Filter by exact event `type`, `since`,
or exclusive `until`. A page contains at most 100 items and includes an opaque
`nextCursor` when more items remain.

```bash cURL
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events?type=message.received&limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
for await (const event of await project.events.list({ type: "message.received", limit: 100 })) {
  console.log(event.id, event.type, event.createdAt, event.payloadAvailability);
}
```

*TypeScript:*

A project client sees its project. A team client sees team events and every
project's events. The loop fetches the next pages for you; see
[Read every page in the SDK](https://docs.polymorfa.com/api/pagination#sdk).

Do not modify or decode a cursor. A cursor is bound to its owner and filters.
Send it with `limit` only; changing the filters returns `invalid_cursor`.

To follow new events in ingestion order, pass `afterOffset=0`. The response
includes `page.highWatermark`, the last committed stream position. Use that
value as `afterOffset` on the next request to wait for new events. If a response
has `page.hasMore=true`, use `page.nextOffset` first and continue until the
page is exhausted. This mode accepts `type` and `limit`; it cannot be combined
with `cursor`, `since`, or `until`. An event delivered after a reconnect appears
after its stream position even if its `createdAt` is older than earlier events.
Offsets are decimal strings; keep them as strings.

```bash cURL
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events?afterOffset=$OFFSET&limit=100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
import { setTimeout as wait } from "node:timers/promises";

// Baseline: start after everything stored so far.
let offset = (await project.events.listIndexed({ afterOffset: "0", limit: 1 })).page.highWatermark ?? "0";
const stop = new AbortController(); // Call stop.abort() to stop following.

while (!stop.signal.aborted) {
  const result = await project.events.listIndexed({ afterOffset: offset, limit: 100 });
  for (const event of result.items) console.log(event.id, event.type);

  // Keep the saved offset when a page names no later position.
  const next = result.page.hasMore ? result.page.nextOffset : result.page.highWatermark;
  const advanced = next != null && BigInt(next) > BigInt(offset);
  if (advanced) offset = next;
  // Caught up means no more events yet. Wait before asking again; never spin.
  if (!result.page.hasMore || !advanced) await wait(5_000, undefined, { signal: stop.signal }).catch(() => {});
}
```

*TypeScript:*

`listIndexed` returns events in ingestion order. Start from a baseline, then
poll from the saved offset. Drain immediately while `hasMore` is `true`; otherwise
wait a bounded time and poll again.

List results never contain payload bytes. Each event reports:

- its team and optional project owner;
- event type, source, environment, and creation time;
- `payloadAvailability`;
- `replayableUntil` when a retained payload remains replayable; and
- `metadataExpiresAt` for the event record itself.

These timestamps are authoritative. Do not assume a fixed retention duration.

## Retrieve payload bytes

Retrieve metadata without content by default. Add `includePayload=true` to ask
for the exact native webhook body:

```bash cURL
curl "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events/$EVENT_ID?includePayload=true" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const event = await project.events.retrieve("<event-id>", { includePayload: true });

if (event.data.payload) {
  const body = JSON.parse(atob(event.data.payload.data));
  console.log(body);
}
```

When available and still authorized, `payload` contains base64-encoded bytes
with `encoding: "base64"` and `contentType: "application/json"`. Decode those
bytes without parsing and reserializing them when you need the original body.

A null payload is not reconstructed from metadata. Check
`payloadAvailability` and `replayableUntil` on every response. Disabling the
content-retention grant for the exact source session makes its retained content
unavailable immediately, even if its metadata remains visible.

Event metadata never includes signing secrets, authorization headers, cookies,
raw network errors, or webhook response bodies.

## Replay an event

Replay creates a new logical delivery for one existing event and one webhook:

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events/$EVENT_ID/replays" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "webhookId": "'"$WEBHOOK_ID"'" }'
```

```typescript TypeScript
const replay = await project.events.replay(
  "<event-id>",
  { webhookId: "<webhook-id>" },
  { idempotencyKey: crypto.randomUUID() },
);

console.log(replay.data.deliveryId, replay.data.operationId);
```

Send `webhookId` in the JSON body and an `Idempotency-Key` header. For a team
event, use `POST /platform/events/{eventId}/replays`. The route requires
`events:replay`; it does not use the delivery-retry permission. The
event and webhook must have the same owner, and the server rechecks payload
availability in the mutation transaction.

The response immediately identifies the original event, the new delivery, the
asynchronous operation, and the idempotency receipt. It does not wait for the
network attempt to finish. If the exact body is unavailable or past
`replayableUntil`, the request returns `payload_not_replayable` without
creating a delivery.

Replay preserves the original event and every existing delivery. Use delivery
retry when you need another attempt on an existing logical delivery.
