Events API reference
Updated
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.
- 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/eventsEvents 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 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.
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
| 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
| 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
| 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_..."