GET /v1/events

GET /v1/events

Your project's event history in this key's environment, newest first: the events your webhooks are sent and your stream frames, read back. Use it to catch up on what happened before you were listening. The stream starts from now or from an id you already hold, and a webhook endpoint is sent only what happens after it subscribes; neither reads back.

curl "https://api.mapier.ai/v1/events?type=message.received,command.settled&limit=2" \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "x-mapier-version: 2026-10-15"

{
  "events": [
    {
      "id": "0192a7c4-6a02-7e11-8c4d-2b9f7e3a5d10",
      "type": "message.received",
      "occurredAt": "2026-08-24T18:03:11.000Z",
      "data": {
        "conversationId": "a0000000-0000-4000-8000-000000000001",
        "from": "+14155550100",
        "text": "is it here yet?",
        "externalId": "guid-1",
        "replyToExternalId": null,
        "occurredAt": "2026-08-24T18:03:11.000Z",
        "attachmentIds": [],
        "attachments": [],
        "messageId": "0192a7c4-6a02-7e11-8c4d-2b9f7e3a5d22",
        "lineId": "0192a7b0-3e4f-7051-8c6d-7e8f9a0b1c2d",
        "contactId": "c0000000-0000-4000-8000-000000000003",
        "optedOut": false
      }
    },
    {
      "id": "0192a7c4-5b1e-7c3d-9f2a-6e8d4b1c0a37",
      "type": "command.settled",
      "occurredAt": "2026-08-24T18:01:02.000Z",
      "data": {
        "commandId": "3f1a0c2e-8b47-4d19-9a5e-2c6f0b8d4e71",
        "logicalActionId": "order-2481",
        "status": "succeeded",
        "errorCode": null,
        "conversationId": "a0000000-0000-4000-8000-000000000001",
        "type": "message.send",
        "messageId": "0192a7c4-5b1e-7c3d-9f2a-6e8d4b1c0a99",
        "externalId": null,
        "namePhoto": null,
        "projectId": "b0000000-0000-4000-8000-000000000002",
        "environment": "live",
        "failureClass": null
      }
    }
  ],
  "nextCursor": "…"
}

Request

Omit type and the list is the types a new webhook endpoint is subscribed to by default. The nine opt-in types are listed only when type names them, as a webhook endpoint and the stream treat them: location.share_started, location.updated, location.share_ended, message.edited, message.unsent, poll.created, poll.options_changed, poll.voted and poll.vote_cleared.

from and to filter on when an event was recorded. For most events that is its occurredAt. An inbound event — a message, a receipt, a reaction — is recorded later, by however long the platform took to tell us: usually seconds, longer after a connection outage. So a to copied from an inbound event's occurredAt can leave that event out.

Page with cursor: pass each answer's nextCursor back, with the same filters, until it is null. A cursor past the last page answers an empty page. A cursor is opaque: never build or parse one.

The response

events is one page, newest first, and nextCursor is the cursor for the next, older page, or null on the last.

Each type the stream frames carries that frame as its data:

Every other type — message.sent, message.failed, reaction.added, conversation.created, line.status_changed and the rest — carries the data a webhook subscribed to it is sent.

Read back, then follow

Any id you read here is a Last-Event-ID that /v1/response_stream resumes after, so you can read back and then follow. Resume from an id a few seconds older than the newest you read, and deduplicate on id. An event's id is taken as it is written and the event is listed once that write commits, so an event can appear with an id a moment older than one you have already read.

How long events are kept

Events are kept at least 90 days; some are kept longer. A test key reads the sandbox's events.

Errors

Related