---
title: "List messages"
method: GET
path: "/v1/objects/{collection}/{id}/messages"
tags: ["Messages", "Objects"]
---

# List messages

`GET /v1/objects/{collection}/{id}/messages`

Returns a paginated list of messages for a specific object in the given collection. Allows filtering by message status and provides various sorting options.

## Path parameters

- `collection` string, required
- `id` string, required

## Query parameters

- `after` string
- `before` string
- `page_size` integer
- `tenant` string
- `channel_id` string
- `status[]` string[]
- `engagement_status[]` string[]
- `message_ids[]` string[]
- `workflow_categories[]` string[]
- `source` string
- `workflow_run_id` string, uuid
- `workflow_recipient_run_id` string, uuid
- `trigger_data` string
- `inserted_at.gt` string
- `inserted_at.gte` string
- `inserted_at.lt` string
- `inserted_at.lte` string

## Response `200`

OK

- ListMessagesResponse — A paginated list of messages.
  - `items` Message[], required — A list of messages.
    - `__typename` string, required — The typename of the schema.
    - `actors` RecipientReference[] — One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a [batch](/designing-workflows/batch-function).
      - union — A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
        - string — The ID of the user which is used as the reference for the recipient.
        - object — A reference to a recipient object.
          - `collection` string — The collection the recipient object belongs to.
          - `id` string — An identifier for the recipient object.
    - `archived_at` string, date-time, nullable — Timestamp when the message was archived.
    - `channel` object — A configured channel, which is a way to route messages to a provider.
      - `created_at` string, date-time, required — The timestamp of when the channel was created.
      - `id` string, required — The unique identifier for the channel.
      - `key` string, nullable — Unique identifier for the channel within a project (immutable once created).
      - `name` string, nullable — The human-readable name of the channel.
      - `provider` string, required — The ID of the provider that this channel uses to deliver messages.
      - `type` 'email' | 'in_app' | 'in_app_feed' | 'in_app_guide' | 'sms' | 'push' | 'chat' | 'http', required — The type of channel, determining what kind of messages it can send.
      - `updated_at` string, date-time, required — The timestamp of when the channel was last updated.
    - `channel_id` string, uuid, required — Deprecated, use channel.id instead.
    - `clicked_at` string, date-time, nullable — Timestamp when the message was clicked.
    - `data` object, nullable — Data associated with the message’s workflow run. Includes the workflow trigger request’s `data` payload merged with any additional data returned by a [fetch function](/designing-workflows/fetch-function). For messages produced after a [batch step](/designing-workflows/batch-function), includes the payload `data` from the most-recent trigger request (the final `activity` in the batch).
    - `engagement_statuses` string[], required — A list of engagement statuses.
    - `id` string, required — The unique identifier for the message.
    - `inserted_at` string, date-time, required — Timestamp when the resource was created.
    - `interacted_at` string, date-time, nullable — Timestamp when the message was interacted with.
    - `link_clicked_at` string, date-time, nullable — Timestamp when a link in the message was clicked.
    - `metadata` object, nullable — The metadata associated with the message.
    - `read_at` string, date-time, nullable — Timestamp when the message was read.
    - `recipient` union, required — A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).
      - string — The ID of the user which is used as the reference for the recipient.
      - object — A reference to a recipient object.
        - `collection` string — The collection the recipient object belongs to.
        - `id` string — An identifier for the recipient object.
    - `scheduled_at` string, date-time, nullable — Timestamp when the message was scheduled to be sent.
    - `seen_at` string, date-time, nullable — Timestamp when the message was seen.
    - `source` object, required — The workflow or guide that triggered the message.
      - `__typename` string, required
      - `categories` string[], required — The categories associated with the message.
      - `key` string, required — The key of the workflow or guide that triggered the message.
      - `step_ref` string, nullable — The step reference for the step in the workflow that generated the message.
      - `type` 'broadcast' | 'workflow' | 'guide' — Whether this message was generated from a workflow, broadcast, or guide.
      - `version_id` string, uuid, required — The ID of the version of the workflow or guide that triggered the message.
      - `workflow_recipient_run_id` string, uuid, nullable — The unique identifier for the workflow recipient run that generated this message. Only present for workflow/broadcast messages.
      - `workflow_run_id` string, uuid, nullable — The unique identifier for the workflow run that generated this message. Only present for workflow/broadcast messages.
    - `status` 'queued' | 'sent' | 'delivered' | 'delivery_attempted' | 'undelivered' | 'not_sent' | 'bounced', required — The message delivery status.
    - `tenant` string, nullable — The ID of the `tenant` associated with the message. Only present when a `tenant` is provided on a workflow trigger request.
    - `updated_at` string, date-time, required — The timestamp when the resource was last updated.
    - `workflow` string, nullable — The key of the workflow that generated the message.
  - `page_info` PageInfo, required — Pagination information for a list of resources.
    - `__typename` string, required — The typename of the schema.
    - `after` string, nullable — The cursor to fetch entries after.
    - `before` string, nullable — The cursor to fetch entries before.
    - `page_size` integer, required — The number of items per page (defaults to 50).

---

[API](https://skmtc.net/knocklabs/apis/knock-api.md) · [All operations](https://skmtc.net/knocklabs/apis/knock-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/knocklabs/knock-api/revisions/4b8499dddbc5/schema)