# Events API reference

> One operation of the Fax for Agents API. GET /v1/events returns every event in order, oldest first from a cursor, so a client can catch up after an outage.

Page: https://faxforagents.com/docs/api/reference/events/
Last changed: 2026-11-13

Updated Nov 13, 2026

1 operation of the Fax for Agents API, from the OpenAPI document version 1.20.0, snapshot of 2026-11-13. The base URL is `https://api.faxforagents.com/v1`. This is one group of the [full reference](https://faxforagents.com/docs/api/reference/).

- GET /v1/events returns events oldest first, starting from the cursor you send.
- The event log holds the same events the webhooks deliver, whether or not a delivery succeeded.
- Reading the event log needs the scope fax:read.

## Operations

- `GET /v1/events` Events for reconciliation, oldest first from the cursor

## What is the event log for?

Reconciliation. A webhook delivery can fail: your receiver was down, a deploy dropped a request, a queue lost a message. `GET /v1/events` serves the same events in sequence order, so a client can ask for everything since the last one it handled.

## How do I read it?

Send the `cursor` you stored after the last page. The answer has `items`, oldest first from that cursor, and `next_cursor`. Call again with `next_cursor` while the answer carries one. The last page has none. `limit` sets the page size. `type` narrows the log to one event type, such as `fax.delivered`.

Without a cursor the log starts at the beginning. The cursor is opaque, so store it as it came. A client that keeps it in durable storage misses nothing. Handling an event twice does no harm when the client deduplicates on the event id, as a webhook handler should.

## How does it relate to webhooks?

The [webhooks group](https://faxforagents.com/docs/api/reference/webhooks/) pushes events to your URL and lists each delivery attempt. This group is the pull side of the same stream. The two work together: webhooks for speed, and a walk of the log on a timer to prove that nothing was lost. The events of one fax alone are under the [faxes group](https://faxforagents.com/docs/api/reference/faxes/).

The call needs `fax:read`.

## Each operation in detail

### GET `/v1/events`

Events for reconciliation, oldest first from the cursor

Credential: an API key or a signed-in session. Scope: `fax:read`.

#### Parameters

GET /v1/events parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `type` | query | string or null | no |  |
| `cursor` | query | string or null | no | The cursor from the previous page (opaque). |
| `limit` | query | integer | no | Default `100` . |

#### Responses

GET /v1/events responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/events response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Event | yes |  |
| `next_cursor` | string or null | no |  |

#### Example

```
`curl https://api.faxforagents.com/v1/events \ -H "Authorization: Bearer ffa_test_..."`
```