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

# List schedules

> Returns paginated schedule groups, each with its nested interview events. Record timestamp filters narrow the schedule records and are combined with IDs when supplied. Use the cursor to continue the same filtered result set.

<Note>**Beta**: this endpoint may change or be removed without notice while in beta. There is no compatibility promise until it reaches general availability.</Note>


## OpenAPI

````yaml /openapi.json get /v1/schedules
openapi: 3.1.0
info:
  title: ModernLoop Platform API
  version: 0.1.0
  description: The ModernLoop Platform API for managing recruiting workflows.
  contact:
    email: support@modernloop.io
servers:
  - url: https://api.modernloop.io
security: []
tags:
  - name: Application
  - name: Candidate
  - name: Interview Event
  - name: Interview Module
  - name: Interviewer
  - name: Job
  - name: Job Stage
  - name: Organization
  - name: Schedule
  - name: Scheduling Task
  - name: Task Queue
  - name: Template
paths:
  /v1/schedules:
    get:
      tags:
        - Schedule
      summary: List schedules
      description: >-
        Returns paginated schedule groups, each with its nested interview
        events. Record timestamp filters narrow the schedule records and are
        combined with IDs when supplied. Use the cursor to continue the same
        filtered result set.
      operationId: listSchedules
      parameters:
        - schema:
            type: string
            description: >-
              Opaque pagination cursor from the previous page's
              pagination.next_cursor, bound to the same query filters.
          required: false
          description: >-
            Opaque pagination cursor from the previous page's
            pagination.next_cursor, bound to the same query filters.
          name: cursor
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
            description: Page size. Must be between 1 and 100; defaults to 25.
          required: false
          description: Page size. Must be between 1 and 100; defaults to 25.
          name: limit
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
              pattern: >-
                ^(?:sch_)?(?:[0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              description: >-
                a schedule ID. Accepts the canonical prefixed compact UUID, a
                prefixed dashed UUID, a bare dashed UUID, or a bare compact
                UUID; input is case-insensitive.
              example: sch_a1b2c3d4e5f64789a1b2c3d4e5f64789
            description: Comma-separated list of IDs; maximum 100 values.
          required: false
          description: Comma-separated list of IDs; maximum 100 values.
          name: ids
          in: query
          style: form
          explode: false
        - schema:
            type: string
            format: date-time
            description: Filters records created at or after this timestamp.
          required: false
          description: Filters records created at or after this timestamp.
          name: created_at_gte
          in: query
        - schema:
            type: string
            format: date-time
            description: Filters records created at or before this timestamp.
          required: false
          description: Filters records created at or before this timestamp.
          name: created_at_lte
          in: query
        - schema:
            type: string
            format: date-time
            description: Filters records updated at or after this timestamp.
          required: false
          description: Filters records updated at or after this timestamp.
          name: updated_at_gte
          in: query
        - schema:
            type: string
            format: date-time
            description: Filters records updated at or before this timestamp.
          required: false
          description: Filters records updated at or before this timestamp.
          name: updated_at_lte
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Schedule'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                  - data
                  - pagination
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    Schedule:
      type: object
      properties:
        id:
          type: string
          pattern: ^sch_[0-9a-f]{32}$
          description: >-
            Canonical schedule ID (sch_ followed by 32 lowercase hexadecimal
            UUID characters).
          example: sch_a1b2c3d4e5f64789a1b2c3d4e5f64789
        application:
          type: object
          properties:
            id:
              type: string
              pattern: ^app_[0-9a-f]{32}$
              description: >-
                Canonical application ID (app_ followed by 32 lowercase
                hexadecimal UUID characters).
              example: app_a1b2c3d4e5f64789a1b2c3d4e5f64789
            candidate:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^can_[0-9a-f]{32}$
                  description: >-
                    Canonical candidate ID (can_ followed by 32 lowercase
                    hexadecimal UUID characters).
                  example: can_a1b2c3d4e5f64789a1b2c3d4e5f64789
                name:
                  type: string
              required:
                - id
                - name
            job:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^job_[0-9a-f]{32}$
                  description: >-
                    Canonical job ID (job_ followed by 32 lowercase hexadecimal
                    UUID characters).
                  example: job_a1b2c3d4e5f64789a1b2c3d4e5f64789
                name:
                  type: string
              required:
                - id
                - name
            stage:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^stg_[0-9a-f]{32}$
                  description: >-
                    Canonical job stage ID (stg_ followed by 32 lowercase
                    hexadecimal UUID characters).
                  example: stg_a1b2c3d4e5f64789a1b2c3d4e5f64789
                name:
                  type: string
              required:
                - id
                - name
          required:
            - id
            - candidate
            - job
            - stage
        status:
          type: string
          enum:
            - SCHEDULED
            - PARTIALLY_DECLINED
            - CANCELED
        start_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        end_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        timezone:
          type: string
        interviews:
          type: array
          items:
            $ref: '#/components/schemas/InterviewEvent'
        task:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              pattern: ^tsk_[0-9a-f]{32}$
              description: >-
                Canonical task ID (tsk_ followed by 32 lowercase hexadecimal
                UUID characters).
              example: tsk_a1b2c3d4e5f64789a1b2c3d4e5f64789
          required:
            - id
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        app_url:
          type: string
          format: uri
      required:
        - id
        - application
        - status
        - start_at
        - end_at
        - timezone
        - interviews
        - task
        - created_at
        - updated_at
        - app_url
    Pagination:
      type: object
      properties:
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - next_cursor
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - UNAUTHENTICATED
                - API_ACCESS_DISABLED
                - SCOPE_MISSING
                - INSUFFICIENT_SCOPE
                - VALIDATION_FAILED
                - INVALID_CURSOR
                - PAYLOAD_TOO_LARGE
                - NOT_FOUND
                - NOT_FOUND_MAY_BE_SYNCING
                - CANDIDATE_ANONYMIZED
                - TASK_STAGE_NOT_SCHEDULABLE
                - DUPLICATE_REQUEST_OPEN
                - IDEMPOTENCY_KEY_REQUIRED
                - IDEMPOTENCY_KEY_REUSED
                - PREVIEW_EXPIRED
                - PREVIEW_STALE
                - RATE_LIMITED
                - CONFLICT
                - NOT_IMPLEMENTED
                - INTERNAL
                - UPSTREAM_TIMEOUT
            message:
              type: string
            docs_url:
              type: string
              format: uri
          required:
            - code
            - message
      required:
        - error
    InterviewEvent:
      type: object
      properties:
        id:
          type: string
          pattern: ^int_[0-9a-f]{32}$
          description: >-
            Canonical interview event ID (int_ followed by 32 lowercase
            hexadecimal UUID characters).
          example: int_a1b2c3d4e5f64789a1b2c3d4e5f64789
        schedule_id:
          type: string
          pattern: ^sch_[0-9a-f]{32}$
          description: >-
            Canonical schedule ID (sch_ followed by 32 lowercase hexadecimal
            UUID characters).
          example: sch_a1b2c3d4e5f64789a1b2c3d4e5f64789
        name:
          type: string
        start_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        end_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        timezone:
          type: string
        status:
          type: string
          enum:
            - SCHEDULED
            - COMPLETED
            - CANCELED
        application:
          type: object
          properties:
            id:
              type: string
              pattern: ^app_[0-9a-f]{32}$
              description: >-
                Canonical application ID (app_ followed by 32 lowercase
                hexadecimal UUID characters).
              example: app_a1b2c3d4e5f64789a1b2c3d4e5f64789
            candidate:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^can_[0-9a-f]{32}$
                  description: >-
                    Canonical candidate ID (can_ followed by 32 lowercase
                    hexadecimal UUID characters).
                  example: can_a1b2c3d4e5f64789a1b2c3d4e5f64789
                name:
                  type: string
              required:
                - id
                - name
            job:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^job_[0-9a-f]{32}$
                  description: >-
                    Canonical job ID (job_ followed by 32 lowercase hexadecimal
                    UUID characters).
                  example: job_a1b2c3d4e5f64789a1b2c3d4e5f64789
                name:
                  type: string
              required:
                - id
                - name
            stage:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^stg_[0-9a-f]{32}$
                  description: >-
                    Canonical job stage ID (stg_ followed by 32 lowercase
                    hexadecimal UUID characters).
                  example: stg_a1b2c3d4e5f64789a1b2c3d4e5f64789
                name:
                  type: string
              required:
                - id
                - name
          required:
            - id
            - candidate
            - job
            - stage
        interviewers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^emp_[0-9a-f]{32}$
                description: >-
                  Canonical employee ID (emp_ followed by 32 lowercase
                  hexadecimal UUID characters).
                example: emp_a1b2c3d4e5f64789a1b2c3d4e5f64789
              name:
                type: string
              role:
                type: string
                enum:
                  - INTERVIEWER
                  - SHADOW
                  - REVERSE_SHADOW
              rsvp:
                type: string
                enum:
                  - ACCEPTED
                  - DECLINED
                  - TENTATIVE
                  - NEEDS_ACTION
                  - MISSED
            required:
              - id
              - name
              - role
              - rsvp
        video_meeting_url:
          type:
            - string
            - 'null'
          format: uri
        is_debrief:
          type: boolean
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp.
      required:
        - id
        - schedule_id
        - name
        - start_at
        - end_at
        - timezone
        - status
        - application
        - interviewers
        - video_meeting_url
        - is_debrief
        - created_at
        - updated_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API tokens are passed as Bearer tokens.

````