---
title: "Lists scheduled 1:1 messages."
method: GET
path: "/dashboards/{dashboard_id}/scheduledmessages"
tags: ["Scheduled Messages"]
---

# Lists scheduled 1:1 messages.

`GET /dashboards/{dashboard_id}/scheduledmessages`

Returns all pending scheduled **1:1** messages for a dashboard. Excludes group messages. Each item's **message_id** is the value returned when the message was scheduled via POST /messages or POST /dashboards/{dashboard_id}/contacts/{phone_number}/messages.

## Path parameters

- `dashboard_id` integer, required

## Query parameters

- `page` integer
- `page_size` integer
- `schedule_date_after` string, date-time
- `schedule_date_before` string, date-time
- `recurring_only` boolean

## Response `200`

Scheduled 1:1 messages for this dashboard.

- ScheduledMessageResponseContainer
  - `meta` PaginationInfo
    - `page` integer — The current page of this get request
    - `page_size` integer — The current page-size of this get request
    - `total_items` integer — The total number of queryable items
  - `items` ScheduledMessage[]
    - `message_id` string, uuid — The scheduled message's unique identifier.
    - `status` 'scheduled' — Scheduled message status.
    - `body` string — The message body.
    - `to` string — The recipient phone number.
    - `date_created` string, date-time — UTC timestamp when the scheduled message was created.
    - `schedule_date_utc` string, date-time — UTC timestamp of the next scheduled send.
    - `occurrence_number` integer — For recurring messages, which occurrence is next. Omitted for non-recurring messages.
    - `mms_media` string[] — MMS media URLs attached to this message.
    - `repeat_settings` RepeatSettings — Controls how a scheduled message repeats. Only include this when creating a **recurring** message; one-time scheduled sends use **schedule_date_utc** alone. ### Required fields | Field | Rule | |-------|------| | **repeat_by** | Required. Must be `day`, `week`, `month`, or `year` (plural forms `days`, `weeks`, `months`, `years` are also accepted). | | **step** | Required. Must be an integer **≥ 1**. See **Understanding step** below. | | **schedule_date_utc** | Required on the parent request whenever **repeat_settings** is present. Must be a **future** UTC timestamp for the **first** send. | ### Understanding step **`step`** is the number **N** in "every N {repeat_by units}". It only has meaning together with **`repeat_by`** — the unit comes from `repeat_by`, and `step` says how many of those units between sends. | step | repeat_by | Meaning | |------|-----------|--------| | 1 | `day` | Every day | | 2 | `day` | Every 2 days | | 3 | `day` | Every 3 days | | 14 | `day` | Every 14 days | | 1 | `week` | Every week | | 2 | `week` | Every 2 weeks (biweekly) | | 4 | `week` | Every 4 weeks | | 1 | `month` | Every month (same day of month as **schedule_date_utc**) | | 2 | `month` | Every 2 months | | 3 | `month` | Every 3 months (quarterly) | | 1 | `year` | Every year (same month/day as **schedule_date_utc**) | | 2 | `year` | Every 2 years | **Weekly + days:** When **repeat_by** is `week` and **days** is set (e.g. `["Monday", "Wednesday"]`), **step** is the gap between *weeks* that contain sends. `step: 1` = Mon/Wed every week; `step: 2` = Mon/Wed on alternate weeks only. **First send:** Always at **schedule_date_utc**. Later sends follow the interval above. ### Optional stop conditions (pick one or neither) | Field | Rule | |-------|------| | **times** | Stop after this many total sends (including the first). | | **end_date** | Stop after this UTC date. Must be in the future. | | *(neither)* | The series repeats until you cancel it. | **You cannot set both `times` and `end_date` in the same request.** ### Repeat mode reference | repeat_by | Meaning (N = **step**) | Extra fields | |-----------|------------------------|--------------| | `day` | Repeats every **N** day(s) | — | | `week` | Repeats every **N** week(s) | Optional **days** array for specific weekdays | | `month` | Repeats every **N** month(s) on the same day of month as **schedule_date_utc** | — | | `year` | Repeats every **N** year(s) on the same month/day as **schedule_date_utc** | — | ### Not allowed * **repeat_settings** without **schedule_date_utc** * **schedule_date_utc** or **end_date** in the past * **step** omitted or `0` * **times** and **end_date** together * Invalid **repeat_by** values * Scheduling with **authvia_conversation_id**, **geolocation_requested**, or **location_callback** (on 1:1 send endpoints)
      - `repeat_by` 'day' | 'week' | 'month' | 'year', required — The unit of time between sends. Accepted values: `day`, `week`, `month`, `year` (plural forms are also accepted by the API).
      - `step` integer, required — How many **repeat_by** units between sends (the **N** in "every N days/weeks/months/years"). Examples: `step: 1` + `repeat_by: day` = daily; `step: 14` + `repeat_by: day` = every 14 days; `step: 2` + `repeat_by: week` = biweekly; `step: 3` + `repeat_by: month` = quarterly. Must be ≥ 1. See the **repeat_settings** schema for the full table.
      - `times` integer — Stop the series after this many total sends (including the first). **Mutually exclusive with end_date.** Omit both **times** and **end_date** to repeat until cancelled.
      - `end_date` string, date-time — UTC timestamp after which no further sends occur. Must be in the future. **Mutually exclusive with times.**
      - `days` string[] — Only applies when **repeat_by** is `week`. Limits sends to these weekdays. Day names are case-insensitive (e.g. `Monday` or `monday`).

## Other responses

- `401` — Unauthorized. Sent if the API key is omitted or invalid.

---

[API](https://skmtc.net/textrequest/apis/text-request-api-v3.md) · [All operations](https://skmtc.net/textrequest/apis/text-request-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/textrequest/text-request-api-v3/revisions/e4e42efcd650/schema)