# List scheduled messages

`GET /chat.scheduled.list`

## Description

Lists pending messages scheduled via [`/chat.post`](/docs/api/chat-post)'s `sendAt`
that have not been sent yet. Results are ordered ascending by `sendAt` (soonest
first). Sent and canceled messages are not returned.

Only messages scheduled by the calling credential's bot identity are listed:
organization tokens of the same app share the app's bot identity (and therefore
see each other's scheduled messages), while personal access tokens have a
per-person bot identity and see only their own.

**Access:** Organization and Personal.

**Required scope:** `chat:send_message` or `chat:write`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `chatId` | query | string | No | Only return messages scheduled for this chat. |
| `after` | query | string | No | Only return messages scheduled to send after this datetime (YYYY-MM-DD or RFC-3339). Exclusive.  |
| `before` | query | string | No | Only return messages scheduled to send before this datetime (YYYY-MM-DD or RFC-3339). Exclusive.  |
| `limit` | query | integer | No | The number of scheduled messages to return per response. Default is 10. |
| `cursor` | query | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Do not construct cursors manually. |

## Responses

### 200 - OK

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `scheduledMessages` | object[] | No |  |
| `nextCursor` | string | No | Returned if there is a subsequent page of scheduled messages. |

**scheduledMessages** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `scheduledMessageId` | string | No | The id returned by `/chat.post` when the message was scheduled; pass to `/chat.scheduled.cancel`. |
| `chatId` | string | No | The chat the message will be posted to. |
| `threadTimestamp` | integer | No | Thread the message will post into (present only when scheduled with `threadTimestamp`; unix micros, matching `/chat.post` and `/chat.history` message keys). |
| `sendAt` | string | No | When the message is scheduled to send (RFC 3339). |
| `createdAt` | string | No | When the message was scheduled (RFC 3339). |
| `text` | string | No | Preview snippet of the message text, truncated server-side. Empty for non-text content such as Block Kit messages. |


#### Example Response

```json
{
  "scheduledMessages": [
    {
      "scheduledMessageId": "0197f9f0-5cc1-7d07-8a12-9e65a8a0c1b9",
      "chatId": "757dfe66-37b4-4772-baa5-8c86ec68c176",
      "sendAt": "2026-08-01T14:30:00Z",
      "createdAt": "2026-07-20T09:12:44Z",
      "text": "Reminder: sprint review starts in 15 minutes"
    }
  ],
  "nextCursor": "YzE6MTc1NDA2MzgwMDAwMDowMTk3ZjlmMC01Y2Mx"
}
```

### 400 - Bad request. Common causes:
- Invalid `chatId`, `after`, `before`, or `limit`
- Invalid or expired `cursor` (`invalid_cursor`) — restart without a cursor


### 401 - Presented invalid authentication credentials.

### 403 - Token lacks a required scope (`missing_scope`).

### 405 - An unsupported method was requested.

### 500 - An internal error occured.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/chat-scheduled-list*