---
title: "Read retained events"
method: GET
path: "/api/v1/events"
tags: ["Events"]
---

# Read retained events

`GET /api/v1/events`

## Request

- Base URL: `https://app.probbai.com`
- URL: `https://app.probbai.com/api/v1/events`
- Auth: HTTP bearer

Recover notifications missed by your receiver or poll changes without hosting a webhook endpoint. The feed follows durable publication order within your workspace.

## Before you call

Use events:read. Start without a cursor, then retain the returned position. Optional type/reportId/interviewId filters must remain unchanged while following a cursor.

**Required scope:** `events:read`.

## What happens next

Process items durably before saving nextCursor, even on an empty page. Use hasMore to drain retained pages. Deleted bodies appear as minimal tombstones; a cursor is an opaque credential-like value, not an offset.

## Recovery

EVENT_CURSOR_EXPIRED returns 410 after retained history is lost. Reconcile current reports/interviews and establish a fresh position. Polling does not resend webhooks; use catch-up or replay for receiver redelivery.

[Follow the complete workflow](/integration-webhooks/) · [Errors and retries](/api-errors/)

## Query parameters

- `limit` integer
- `cursor` string
- `type` 'batch.completed' | 'report.completed' | 'report.result_ready' | 'report.deleted' | 'report.failed' | 'report.requires_action' | 'webhook.test' | 'interview.invited' | 'interview.started' | 'interview.completed' | 'interview.expired' | 'interview.preparation_failed' | 'interview.result_ready' | 'interview.result_failed' | 'interview.invitation_failed'
- `reportId` string
- `interviewId` string

## Response `200`

Process items durably before saving nextCursor, even on an empty page. Use hasMore to drain retained pages. Deleted bodies appear as minimal tombstones; a cursor is an opaque credential-like value, not an offset.

- object
  - `data` EventPage, required
    - `items` union[], required: Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next.
      - union
        - union
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'batch.completed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'report.result_ready', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'report.deleted', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'interview.invited' | 'interview.started' | 'interview.completed' | 'interview.expired' | 'interview.preparation_failed' | 'interview.result_ready' | 'interview.result_failed' | 'interview.invitation_failed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'report.completed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'report.failed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'report.requires_action', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
          - object
            - `id` string, uuid, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
            - `schemaVersion` 1, required: Public payload format version. Result requests currently support 1; this is independent of the assigned product version.
            - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
            - `type` 'webhook.test', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
            - `data` object, required: Public resource or event payload. Successful API responses wrap their result in data; webhook envelopes contain event-specific data.
              - …
        - object
          - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
          - `type` 'batch.completed' | 'report.completed' | 'report.result_ready' | 'report.deleted' | 'report.failed' | 'report.requires_action' | 'webhook.test' | 'interview.invited' | 'interview.started' | 'interview.completed' | 'interview.expired' | 'interview.preparation_failed' | 'interview.result_ready' | 'interview.result_failed' | 'interview.invitation_failed', required: Event type. Subscribe to the events needed for your workflow and process unknown future types safely.
          - `occurredAt` string, date-time, required: UTC time the event occurred. Delivery may be delayed or out of order.
          - `deleted` true, required: True when the original retained event body has been erased. Only its minimal identity remains.
    - `nextCursor` string, required: Opaque continuation token. Reuse unchanged with the same filters. List endpoints return null at the end; the event feed always returns a position.
    - `hasMore` boolean, required: Whether more retained events are immediately available after this page. Keep nextCursor even when false.

## Other responses

- `400`: Invalid input or cursor
- `401`: Invalid, expired, or revoked API key
- `403`: Disabled organisation or missing scope
- `405`: Method not allowed; consult Allow for supported methods
- `410`: Event recovery cursor is outside retained history
- `429`: Request limit exceeded
- `500`: Unexpected failure
- `503`: Service unavailable

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)