List user messages

Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.

get/v1/users/{user_id}/messages

Path parameters

user_idstring required

The user ID to list messages for.

Query parameters

afterstring

The cursor to fetch entries after.

beforestring

The cursor to fetch entries before.

page_sizeinteger

The number of items per page (defaults to 50).

tenantstring

Limits the results to items with the corresponding tenant.

channel_idstring

Limits the results to items with the corresponding channel ID.

status[]string[]

Limits the results to messages with the given delivery status.

engagement_status[]string[]

Limits the results to messages with the given engagement status.

message_ids[]string[]

Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.

workflow_categories[]string[]

Limits the results to messages related to any of the provided categories.

sourcestring

Limits the results to messages triggered by the given workflow key.

workflow_run_idstring uuid

Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.

workflow_recipient_run_idstring uuid

Limits the results to messages for a specific recipient's workflow run.

trigger_datastring

Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.

inserted_at.gtstring

Limits the results to items inserted after the given date.

inserted_at.gtestring

Limits the results to items inserted after or on the given date.

inserted_at.ltstring

Limits the results to items inserted before the given date.

inserted_at.ltestring

Limits the results to items inserted before or on the given date.

Response

Example response

{
  "items": [
    {
      "__typename": "Message",
      "actors": [
        "mr_arnold",
        "mr_muldoon"
      ],
      "archived_at": null,
      "channel_id": "123e4567-e89b-12d3-a456-426614174000",
      "clicked_at": null,
      "data": {
        "affected_areas": [
          "visitor_center",
          "raptor_pen",
          "trex_paddock"
        ],
        "attraction_id": "paddock_rex_01",
        "evacuation_protocol": "active",
        "message": "Life finds a way",
        "severity": "critical",
        "system_status": "fences_failing"
      },
      "engagement_statuses": [
        "read",
        "seen"
      ],
      "id": "2w3YUpTTOxuDvZFji8OMsKrG176",
      "inserted_at": "1993-06-11T21:15:00Z",
      "interacted_at": null,
      "link_clicked_at": null,
      "metadata": {
        "external_id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "read_at": "1993-06-11T21:30:00Z",
      "recipient": "dr_grant",
      "scheduled_at": null,
      "seen_at": "1993-06-11T21:29:45Z",
      "source": {
        "__typename": "NotificationSource",
        "categories": [
          "security",
          "emergency"
        ],
        "key": "security-breach-alert",
        "step_ref": "alert_step_1",
        "version_id": "123e4567-e89b-12d3-a456-426614174000",
        "workflow_recipient_run_id": "def01234-a56b-78c9-d012-345678901bcd",
        "workflow_run_id": "789e0123-f45a-67b8-c901-234567890abc"
      },
      "status": "sent",
      "tenant": "ingen_isla_nublar",
      "updated_at": "1993-06-11T21:30:05Z",
      "workflow": "security-breach-alert"
    }
  ],
  "page_info": {
    "__typename": "PageInfo",
    "after": null,
    "before": null,
    "page_size": 25
  }
}

Changes

Changed in 7 of the 30 revisions of this API.119

Dec 8, 2025b4f3f80942152See the full diff
- ○
  added the optional property items/items/source/workflow_recipient_run_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/source/workflow_run_id to the response with the 200 status
  response-optional-property-added
Oct 27, 202540ca41599f572See the full diff
- ○
  added the optional property items/items/channel to the response with the 200 status
  response-optional-property-added
- ○
  response property items/items/channel_id deprecated
  response-property-deprecated
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Oct 7, 2025fe051300804a1See the full diff
- ○
  added the optional property items/items/source/type to the response with the 200 status
  response-optional-property-added
Aug 27, 2025de67f68640a09See the full diff
- ○
  the response property items/items/__typename became required for the status 200
  response-property-became-required
- ○
  the response property items/items/channel_id became required for the status 200
  response-property-became-required
- ○
  the response property items/items/engagement_statuses became required for the status 200
  response-property-became-required
- ○
  the response property items/items/id became required for the status 200
  response-property-became-required
- ○
  the response property items/items/inserted_at became required for the status 200
  response-property-became-required
- ○
  the response property items/items/recipient became required for the status 200
  response-property-became-required
- ○
  the response property items/items/source became required for the status 200
  response-property-became-required
- ○
  the response property items/items/status became required for the status 200
  response-property-became-required
- ○
  the response property items/items/updated_at became required for the status 200
  response-property-became-required
Jul 10, 2025592610bb4a051See the full diff
- ○
  added the optional property items/items/source/step_ref to the response with the 200 status
  response-optional-property-added
May 29, 202546f457b0a70011See the full diff
- ▲
  removed the required property entries from the response with the 200 status
  response-required-property-removed
- ○
  added the required property items to the response with the 200 status
  response-required-property-added
May 21, 2025a552e94c4d043See the full diff
- ○
  added the enum value unarchived to the property items/ of the query request parameter engagement_status[]
  request-parameter-property-enum-value-added
- ○
  added the enum value unread to the property items/ of the query request parameter engagement_status[]
  request-parameter-property-enum-value-added
- ○
  added the enum value unseen to the property items/ of the query request parameter engagement_status[]
  request-parameter-property-enum-value-added

Full history