---
title: "Query scheduled messages"
method: POST
path: "/scheduled_messages/query"
tags: ["product:chat"]
---

# Query scheduled messages

`POST /scheduled_messages/query`

## Request

- Base URL: `https://chat.stream-io-api.com`
- URL: `https://chat.stream-io-api.com/scheduled_messages/query`
- Auth: one of:
  - API key in header `Authorization` and API key in query parameter `api_key` and API key in header `Stream-Auth-Type`
  - API key in query parameter `api_key` and API key in header `Stream-Auth-Type`

Lists the scheduled messages of one user across channels: pending ones first, then failed ones, each by scheduled_at. Client-side requests return the caller's own; server-side requests require user_id

## Request body

- QueryScheduledMessagesRequest, nullable
  - `filter` ScheduledMessagesFilter: Filter for querying scheduled messages
    - `cid` string: Only scheduled messages of this channel
    - `status` string[]: Only these statuses, as reported in each scheduled message's status. One or more of: scheduled, sending, failed
  - `limit` integer: Page size, 1 to 100. Defaults to 20
  - `next` string: Cursor from the previous page
  - `sort` SortParamRequest[]: Only scheduled_at ascending is supported. Pending messages come before failed ones
    - `direction` integer: Direction of sorting, 1 for Ascending, -1 for Descending, default is 1. One of: -1, 1
    - `field` string: Name of field to sort by
    - `type` string: Type of field to sort by. Empty string or omitted means string type (default). One of: number, boolean
  - `user` UserRequest: User request object
    - `custom` object: Custom user data
    - `id` string, required: User ID
    - `image` string: User's profile image URL
    - `invisible` boolean
    - `language` string
    - `name` string: Optional name of user
    - `privacy_settings` PrivacySettingsResponse: The privacy settings of the user.
      - `delivery_receipts` DeliveryReceiptsResponse: The settings for the delivery receipt events.
        - `enabled` boolean
      - `read_receipts` ReadReceiptsResponse: The settings for the read receipt events.
        - `enabled` boolean
      - `typing_indicators` TypingIndicatorsResponse: The settings for typing indicator events.
        - `enabled` boolean
    - `role` string: User's global role
    - `teams` string[]: List of teams the user belongs to
    - `teams_role` object: Map of team-specific roles for the user
  - `user_id` string

## Response `201`

Successful response

- QueryScheduledMessagesResponse, nullable
  - `duration` string, required: Duration of the request in milliseconds
  - `next` string: Cursor for the next page; empty on the last page
  - `scheduled_messages` ScheduledMessageResponse[], required: Pending messages first, then failed ones, each by scheduled_at
    - `channel` ScheduledMessageChannelResponse: The channel of a scheduled message
      - `cid` string, required: Channel CID (<type>:<id>)
      - `id` string, required: Channel ID
      - `image` string: Channel image, from its custom data
      - `name` string: Channel name, from its custom data
      - `type` string, required: Channel type
    - `cid` string, required: The CID of the channel the message will be sent to
    - `created_at` string, date-time, required: Date/time of creation
    - `failure_reason` string: Why sending the message failed. Only set when status is failed. One of: banned, no_permission, channel_frozen, channel_deleted, user_deleted, moderation_blocked, hook_rejected, expired, internal_error, invalid_message, pending_not_supported
    - `id` string, required: Unique identifier of the scheduled message
    - `message` ScheduledMessageContentResponse, required: The message a scheduled message will send
      - `attachments` Attachment[]: Array of message attachments
        - `actions` Action[]
          - `name` string, required
          - `style` string
          - `text` string, required
          - `type` string, required
          - `value` string
        - `asset_url` string
        - `author_icon` string
        - `author_link` string
        - `author_name` string
        - `color` string
        - `custom` object, required
        - `fallback` string
        - `fields` Field[]
          - `short` boolean, required
          - `title` string, required
          - `value` string, required
        - `footer` string
        - `footer_icon` string
        - `giphy` Images
          - `fixed_height` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_height_downsampled` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_height_still` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_width` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_width_downsampled` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_width_still` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `original` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
        - `image_url` string
        - `og_scrape_url` string
        - `original_height` integer
        - `original_width` integer
        - `pretext` string
        - `text` string
        - `thumb_url` string
        - `title` string
        - `title_link` string
        - `type` string: Attachment type (e.g. image, video, url)
      - `custom` object, required
      - `html` string: Contains HTML markup of the message
      - `mentioned_channel` boolean: Whether the message mentions the whole channel
      - `mentioned_group_ids` string[]: IDs of the user groups mentioned in the message
      - `mentioned_here` boolean: Whether the message mentions the online channel members
      - `mentioned_roles` string[]: Roles mentioned in the message
      - `mentioned_users` string[]: IDs of the users mentioned in the message
      - `mml` string: MML content of the message
      - `parent_id` string: ID of parent message (thread)
      - `pin_expires` string, date-time: Date/time the pin expires
      - `pinned` boolean: Whether the message will be pinned when sent
      - `poll_id` string: Identifier of the poll to include in the message
      - `quoted_message_id` string
      - `restricted_visibility` string[]: IDs of the users the message will be visible to
      - `shared_location` ScheduledMessageLocation: The location a scheduled message will share
        - `created_by_device_id` string, required: The ID of the device that created the location.
        - `end_at` string, date-time: The date when the location sharing ends. If it's empty, it means the location sharing is static instead of live.
        - `latitude` number, double: The latitude of the location.
        - `longitude` number, double: The longitude of the location.
      - `show_in_channel` boolean: Whether thread reply should be shown in the channel as well
      - `silent` boolean: Whether message is silent or not
      - `text` string, required: Text of the message
      - `type` string: Contains type of the message. One of: regular, system
    - `scheduled_at` string, date-time, required: Date/time the message is scheduled to be sent
    - `status` string, required: Status of the scheduled message. One of: scheduled, sending, failed, canceled, sent. A message is sending from its first send attempt until it is sent or fails, including while it waits to retry a failed attempt; it cannot be edited, canceled or sent now while sending
    - `updated_at` string, date-time, required: Date/time of the last update
    - `user` UserResponse, required: User response object
      - `avg_response_time` integer
      - `ban_expires` string, date-time: Date when ban expires
      - `banned` boolean, required: Whether a user is banned or not
      - `blocked_user_ids` string[], required
      - `bypass_moderation` boolean
      - `created_at` string, date-time, required: Date/time of creation
      - `custom` object, required: Custom data for this object
      - `deactivated_at` string, date-time: Date of deactivation
      - `deleted_at` string, date-time: Date/time of deletion
      - `devices` DeviceResponse[]: List of devices user is using
        - `created_at` string, date-time, required: The date when the device was created.
        - `disabled` boolean: Whether device is disabled or not
        - `disabled_reason` string: Reason explaining why device had been disabled
        - `hardware_id` string: Stable physical device identifier used to deduplicate pushes across push providers
        - `id` string, required: The device identifier.
        - `push_provider` string, required: Push provider
        - `push_provider_name` string: Push provider name
        - `user_id` string, required: User ID
        - `voip` boolean: When true the token is for Apple VoIP push notifications
      - `id` string, required: Unique user identifier
      - `image` string
      - `invisible` boolean, required
      - `language` string, required: Preferred language of a user
      - `last_active` string, date-time: Date of last activity
      - `name` string: Optional name of user
      - `online` boolean, required: Whether a user online or not
      - `privacy_settings` PrivacySettingsResponse: The privacy settings of the user.
        - `delivery_receipts` DeliveryReceiptsResponse: The settings for the delivery receipt events.
          - `enabled` boolean
        - `read_receipts` ReadReceiptsResponse: The settings for the read receipt events.
          - `enabled` boolean
        - `typing_indicators` TypingIndicatorsResponse: The settings for typing indicator events.
          - `enabled` boolean
      - `push_notifications` PushNotificationSettingsResponse
        - `disabled` boolean
        - `disabled_until` string, date-time
      - `revoke_tokens_issued_before` string, date-time: Revocation date for tokens
      - `role` string, required: Determines the set of user permissions
      - `shadow_banned` boolean, required: Whether a user is shadow banned
      - `teams` string[], required: List of teams user is a part of
      - `teams_role` object
      - `updated_at` string, date-time, required: Date/time of the last update

## Other responses

- `400`: Bad request
- `429`: Too many requests

## Changes

> 574 revisions in range; 3 not diffed.

- **2026-10-15** `ddeb57744df3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getstream/apis/stream-api/changes/scheduled_messages/query/post.md)

---

[API](https://skmtc.dev/getstream/apis/stream-api.md) - [All operations](https://skmtc.dev/getstream/apis/stream-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getstream/apis/stream-api/revisions/1fda44d40b27?raw)