> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periskope.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List Scheduled Messages

> Returns the scheduled messages of the workspace, by next run time. Filter by chat, creator, status and repetition, search the message text, and restrict to a scheduled_at window.



## OpenAPI

````yaml api-reference/openapi-generated.json GET /v1/message/scheduled
openapi: 3.0.3
info:
  title: Periskope API
  version: 1.0.0
  description: >-
    Periskope external API.


    Responses use a flat, unwrapped shape: most endpoints return the resource at
    the top level, and list endpoints return a wrapper object with pagination
    inline (e.g. `{ from, to, count, chats: [...] }`). The documented response
    schemas describe these shapes directly.
servers:
  - url: https://api.periskope.app
security:
  - bearerAuth: []
paths:
  /v1/message/scheduled:
    get:
      tags:
        - Scheduled Messages
      summary: List scheduled messages
      description: >-
        Returns the scheduled messages of the workspace, by next run time.
        Filter by chat, creator, status and repetition, search the message text,
        and restrict to a scheduled_at window.
      operationId: listScheduledMessages
      parameters:
        - schema:
            type: integer
            nullable: true
            minimum: 0
            description: >-
              Number of records to skip before the first returned record. Use
              together with limit to paginate: page N is offset = N * limit.
              Defaults to 0.
            example: 0
          required: false
          description: >-
            Number of records to skip before the first returned record. Use
            together with limit to paginate: page N is offset = N * limit.
            Defaults to 0.
          name: offset
          in: query
        - schema:
            type: integer
            minimum: 1
            description: Maximum number of records to return in one page. Defaults to 1000.
            example: 1000
          required: false
          description: Maximum number of records to return in one page. Defaults to 1000.
          name: limit
          in: query
        - schema:
            type: string
            description: Only messages whose next run is at or after this time (ISO 8601).
            example: '2026-01-01T00:00:00Z'
          required: false
          description: Only messages whose next run is at or after this time (ISO 8601).
          name: start_time
          in: query
        - schema:
            type: string
            description: Only messages whose next run is at or before this time (ISO 8601).
            example: '2026-01-31T23:59:00Z'
          required: false
          description: Only messages whose next run is at or before this time (ISO 8601).
          name: end_time
          in: query
        - schema:
            type: string
            description: >-
              Case-insensitive substring search on the message text of the
              scheduled content.
            example: reminder
          required: false
          description: >-
            Case-insensitive substring search on the message text of the
            scheduled content.
          name: q
          in: query
        - schema:
            type: string
            description: One or more chat_ids, comma-separated.
            example: 120363000000000000@g.us
          required: false
          description: One or more chat_ids, comma-separated.
          name: chat_id
          in: query
        - schema:
            type: string
            description: One or more creators, comma-separated — member emails or "api".
            example: user@example.com
          required: false
          description: One or more creators, comma-separated — member emails or "api".
          name: performed_by
          in: query
        - schema:
            type: string
            description: >-
              One or more statuses, comma-separated: 'scheduled', 'paused',
              'completed'.
            example: scheduled,paused
          required: false
          description: >-
            One or more statuses, comma-separated: 'scheduled', 'paused',
            'completed'.
          name: status
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Return only repeating (true) or only one-time (false) messages.
            example: 'true'
          required: false
          description: Return only repeating (true) or only one-time (false) messages.
          name: is_repeat
          in: query
        - schema:
            type: string
            enum:
              - scheduled_at
              - created_at
            description: 'Field to sort by: ''scheduled_at'' (default) or ''created_at''.'
            example: scheduled_at
          required: false
          description: 'Field to sort by: ''scheduled_at'' (default) or ''created_at''.'
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: 'Sort direction: ''asc'' or ''desc'' (default).'
            example: desc
          required: false
          description: 'Sort direction: ''asc'' or ''desc'' (default).'
          name: sort_order
          in: query
        - schema:
            type: string
            example: '919876543210'
            description: >-
              Optional. Scope results to a single phone: country code + number
              without symbols or spaces (e.g. 911111111111), or a phone_id
              (phone-xxxxxxxxxxxx). Omit to return data across all phones the
              API token can access.
          required: false
          description: >-
            Optional. Scope results to a single phone: country code + number
            without symbols or spaces (e.g. 911111111111), or a phone_id
            (phone-xxxxxxxxxxxx). Omit to return data across all phones the API
            token can access.
          name: x-phone
          in: header
      responses:
        '200':
          description: Paginated list of scheduled messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: integer
                    description: >-
                      1-based index of the first record in this page (offset +
                      1).
                    example: 1
                  to:
                    type: integer
                    description: 1-based index of the last record in this page.
                    example: 20
                  count:
                    type: integer
                    description: >-
                      Number of records in this page — the length of the
                      `scheduled_messages` array, not the total across all
                      pages.
                    example: 20
                  scheduled_messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduledMessage'
                    description: The scheduled_messages in this page.
              examples:
                default:
                  summary: Response body
                  value:
                    from: 1
                    to: 20
                    count: 20
                    scheduled_messages:
                      - scheduled_id: 00000000-0000-0000-0000-000000000000
                        org_id: 00000000-0000-0000-0000-000000000000
                        org_phone: 911111111111@c.us
                        chat_id: 120363000000000000@g.us
                        message_payload:
                          message: 'Weekly reminder: submit your report'
                          media: {}
                        scheduled_at: '2026-02-01T09:00:00.000Z'
                        is_repeat: true
                        repeat_config:
                          repeat_interval: week
                          repeat_value: 1
                          repeat_days:
                            - monday
                            - friday
                          repeat_ends: '2026-12-31T00:00:00Z'
                        status: scheduled
                        skip_next: false
                        paused_at: null
                        updated_at: null
                        performed_by: api
                        created_at: '2026-01-15T09:30:00.000Z'
        '401':
          description: Invalid, expired or missing API token
          content:
            application/json:
              examples:
                error:
                  summary: Invalid, expired or missing API token
                  value:
                    code: UNAUTHORIZED_ERROR
                    message: Invalid bearer auth token
                    status: 401
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: UNAUTHORIZED_ERROR
                  message:
                    type: string
                    example: Invalid bearer auth token
                  status:
                    type: integer
                    example: 401
                example:
                  code: UNAUTHORIZED_ERROR
                  message: Invalid bearer auth token
                  status: 401
        '422':
          description: Request validation failed
          content:
            application/json:
              examples:
                error:
                  summary: Request validation failed
                  value:
                    code: VALIDATION_ERROR
                    message: Request validation failed
                    status: 422
                    fields:
                      body.chat_id:
                        message: chat_id is required
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: VALIDATION_ERROR
                  message:
                    type: string
                    example: Request validation failed
                  status:
                    type: integer
                    example: 422
                  fields:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        message:
                          type: string
                        value: {}
                    example:
                      body.chat_id:
                        message: chat_id is required
                example:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  status: 422
                  fields:
                    body.chat_id:
                      message: chat_id is required
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              examples:
                error:
                  summary: Rate limit exceeded
                  value:
                    code: RATE_LIMIT_ERROR
                    message: You can only make 100 requests per second
                    status: 429
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: RATE_LIMIT_ERROR
                  message:
                    type: string
                    example: You can only make 100 requests per second
                  status:
                    type: integer
                    example: 429
                example:
                  code: RATE_LIMIT_ERROR
                  message: You can only make 100 requests per second
                  status: 429
        '500':
          description: Internal server error
          content:
            application/json:
              examples:
                error:
                  summary: Internal server error
                  value:
                    code: UNKNOWN_ERROR
                    message: Internal server error
                    status: 500
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: UNKNOWN_ERROR
                  message:
                    type: string
                    example: Internal server error
                  status:
                    type: integer
                    example: 500
                example:
                  code: UNKNOWN_ERROR
                  message: Internal server error
                  status: 500
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: typescript
          label: TypeScript
          source: |-
            import { PeriskopeApi } from '@periskope/periskope-client';

            const client = new PeriskopeApi({
              authToken: 'YOUR_API_KEY',
              phone: '919876543210', // the phone to act with (x-phone)
            });

            async function main() {
              const response = await client.scheduledMessages.listScheduledMessages();
              console.log(response);
            }

            main();
        - lang: bash
          label: cURL
          source: |-
            curl -X GET 'https://api.periskope.app/v1/message/scheduled' \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -H 'x-phone: 919876543210'
components:
  schemas:
    ScheduledMessage:
      type: object
      properties:
        scheduled_id:
          type: string
          description: Unique id of the scheduled message
          example: 00000000-0000-0000-0000-000000000000
        org_id:
          type: string
          description: Id of the organization the scheduled message belongs to
          example: 00000000-0000-0000-0000-000000000000
        org_phone:
          type: string
          description: >-
            Org phone (WhatsApp account) the message is sent from, as country
            code + number suffixed with @c.us
          example: 911111111111@c.us
        chat_id:
          type: string
          description: >-
            Chat the message is sent to — <countrycode><number>@c.us for 1-1
            chats, <group-id>@g.us for group chats
          example: 120363000000000000@g.us
        message_payload:
          type: object
          properties:
            message:
              type: string
              description: Text content of the scheduled message
              example: 'Weekly reminder: submit your report'
            media:
              type: object
              description: Attachment of the scheduled message, when present
          description: Content sent on every run — same shape as POST /message/send
        scheduled_at:
          type: string
          description: >-
            When the next run happens, as an ISO 8601 timestamp. For repeating
            messages this advances after every run.
          example: '2026-02-01T09:00:00.000Z'
        is_repeat:
          type: boolean
          description: Whether the message repeats or sends once
          example: true
        repeat_config:
          $ref: '#/components/schemas/RepeatConfig'
        status:
          type: string
          enum:
            - scheduled
            - paused
            - completed
          description: >-
            Lifecycle status: 'scheduled' (waiting for the next run), 'paused'
            (runs are skipped) or 'completed'
          example: scheduled
        skip_next:
          type: boolean
          description: When true, the next run is skipped once and the series continues
          example: false
        paused_at:
          type: string
          description: >-
            When the schedule was paused, as an ISO 8601 timestamp. null while
            not paused.
        updated_at:
          type: string
          description: >-
            When the schedule completed (one-time message sent, or series
            ended), as an ISO 8601 timestamp. null while pending.
        performed_by:
          type: string
          description: 'Who created the schedule: a member email, or "api"'
          example: api
        created_at:
          type: string
          description: When the schedule was created, as an ISO 8601 timestamp
          example: '2026-01-15T09:30:00.000Z'
      description: >-
        A scheduled message — content sent to a chat at scheduled_at, once or on
        a repeating series
    RepeatConfig:
      type: object
      properties:
        repeat_interval:
          type: string
          enum:
            - day
            - week
            - month
          description: >-
            Unit of repetition: 'day', 'week' or 'month'. Required for repeating
            messages.
          example: week
        repeat_value:
          type: integer
          minimum: 1
          description: >-
            Every how many intervals between runs, e.g. 2 with repeat_interval
            week = every 2 weeks. Defaults to 1. Not applied when repeat_days is
            set — the schedule then runs on the listed weekdays instead.
          example: 1
        repeat_days:
          type: array
          items:
            type: string
            enum:
              - monday
              - tuesday
              - wednesday
              - thursday
              - friday
              - saturday
              - sunday
          description: >-
            Only for repeat_interval 'day': restrict runs to these weekdays,
            e.g. ['monday', 'friday']. The schedule then runs on each listed
            weekday (repeat_value is ignored). Empty or omitted allows every
            day. Not allowed for 'week' or 'month' intervals.
          example:
            - monday
            - friday
        repeat_ends:
          type: string
          description: >-
            When the series stops, as an ISO 8601 UTC timestamp. The series ends
            once the next run would fall after this time. Omit for no end date.
          example: '2026-12-31T00:00:00Z'
      description: How the message recurs. null for one-time messages.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Periskope API token, sent as `Authorization: Bearer <token>`.
        Generate one from the Periskope dashboard under **Settings → API &
        Webhooks**. API access requires an active Pro or Enterprise plan.

````