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

# List schedules

> Lists scheduled automated runs along with a total count for pagination. By default
(scope=mine) it returns only the caller's own schedules; scope=workspace returns all
schedules in the workspace and is admin only (returns 403 otherwise), optionally
narrowed to one owner via owner_user_id. Results can be filtered by lifecycle state,
and archived schedules are excluded unless include_archived is set or an explicit
state filter is given; limit defaults to 100 (max 500) and offset applies to the
workspace view. Each schedule includes its trigger, name, current state, fire and
failure counts, and last and next fire times. Requires the schedules:read scope.



## OpenAPI

````yaml GET /v1/api/schedules
openapi: 3.1.0
info:
  title: HQ API
  description: >-
    Public HTTP API for HQ. Authenticate with a Personal Access Token
    (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an
    OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's
    behalf. Both grant from the same resource:action scope vocabulary; an
    endpoint's required scope is listed under its `security`.
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 1.0.0
servers:
  - url: https://api.hq.zone
    description: HQ API (production)
security: []
tags:
  - name: me
    description: The signed-in user's own account
  - name: conversations
    description: Conversations and their messages
  - name: documents
    description: The content-addressed documents library
  - name: schedules
    description: Scheduled prompts and recurring tasks
  - name: agents
    description: Agents, their skills and integrations
  - name: memory
    description: What the assistant remembers (L5 governance)
  - name: tokens
    description: Personal Access Token management
  - name: billing
    description: Usage and billing
  - name: notifications
    description: In-app notification center
  - name: admin
    description: Workspace administration
  - name: integrations
    description: Workspace integrations (Slack, MCP, skills)
  - name: onboarding
    description: New-workspace onboarding wizard
  - name: auth
    description: Sign-in, sessions, and OAuth
paths:
  /v1/api/schedules:
    get:
      tags:
        - schedules
      summary: List schedules
      description: >-
        Lists scheduled automated runs along with a total count for pagination.
        By default

        (scope=mine) it returns only the caller's own schedules; scope=workspace
        returns all

        schedules in the workspace and is admin only (returns 403 otherwise),
        optionally

        narrowed to one owner via owner_user_id. Results can be filtered by
        lifecycle state,

        and archived schedules are excluded unless include_archived is set or an
        explicit

        state filter is given; limit defaults to 100 (max 500) and offset
        applies to the

        workspace view. Each schedule includes its trigger, name, current state,
        fire and

        failure counts, and last and next fire times. Requires the
        schedules:read scope.
      operationId: list_schedules
      parameters:
        - name: scope
          in: query
          description: '`mine` (default) or `workspace` (admin only).'
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: state
          in: query
          description: |-
            Explicit lifecycle state filter - passes through verbatim. When
            set (e.g. `state=archived`), `include_archived` is ignored.
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: include_archived
          in: query
          description: |-
            When no explicit `state` filter is supplied, default behaviour
            EXCLUDES archived rows so the "your schedules" view shows the
            working set (active + paused + quarantined). Set
            `include_archived=true` for the audit history view.
          required: false
          schema:
            type: boolean
        - name: limit
          in: query
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int64
        - name: offset
          in: query
          description: Row offset for the admin paginator. Ignored for `scope=mine`.
          required: false
          schema:
            type:
              - integer
              - 'null'
            format: int64
        - name: owner_user_id
          in: query
          description: |-
            Restrict a `workspace`-scope listing to one owner (the admin
            "filter by user" dropdown). Ignored for `scope=mine` (which is
            already pinned to the caller).
          required: false
          schema:
            type:
              - string
              - 'null'
            format: uuid
      responses:
        '200':
          description: Schedules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchedulesListResp'
        '400':
          description: Invalid scope (must be 'mine' or 'workspace')
        '403':
          description: scope=workspace requires admin
      security:
        - bearer_pat:
            - schedules:read
        - oauth2:
            - schedules:read
components:
  schemas:
    SchedulesListResp:
      type: object
      required:
        - schedules
        - total
        - limit
        - offset
      properties:
        limit:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleJson'
        total:
          type: integer
          format: int64
          description: |-
            Total rows matching the filter (ignoring limit/offset) - the admin
            paginator's denominator. For `scope=mine` this equals the page size
            today (no paging on the personal view) but is still returned.
    ScheduleJson:
      type: object
      required:
        - id
        - owner_user_id
        - name
        - trigger
        - args
        - state
        - fire_count
        - failure_count
        - consecutive_failure_count
        - max_duration_secs
      properties:
        args: {}
        consecutive_failure_count:
          type: integer
          format: int32
        description:
          type:
            - string
            - 'null'
        failure_count:
          type: integer
          format: int32
        fire_count:
          type: integer
          format: int32
        id:
          type: string
          format: uuid
        last_fire_at:
          type:
            - string
            - 'null'
          format: date-time
        last_fire_lag_ms:
          type:
            - integer
            - 'null'
          format: int64
        last_fire_status:
          type:
            - string
            - 'null'
        last_run_conversation_id:
          type:
            - string
            - 'null'
          format: uuid
          description: |-
            The conversation backing this schedule's most recent run, if any.
            Scheduled-run threads are hidden from the main conversation list;
            the Schedules page uses this to offer a read-only "last run" link.
        max_duration_secs:
          type: integer
          format: int32
          description: >-
            Wall-clock cap per fire (seconds). A fire that runs past it is
            killed

            and marked failed. Editable; default 1800.
        name:
          type: string
        next_fire_at:
          type:
            - string
            - 'null'
          format: date-time
        owner_display_name:
          type:
            - string
            - 'null'
        owner_external_id:
          type:
            - string
            - 'null'
        owner_user_id:
          type: string
          format: uuid
        state:
          type: string
        trigger: {}
  securitySchemes:
    bearer_pat:
      type: http
      scheme: bearer
      bearerFormat: hq_pat
      description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.'
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hq.zone/v1/oauth/authorize
          tokenUrl: https://api.hq.zone/v1/oauth/token
          refreshUrl: https://api.hq.zone/v1/oauth/token
          scopes:
            admin: Administer the workspace (users, settings, integrations)
            agents:read: View the agents in your workspace
            agents:write: Create and configure agents
            billing:read: View usage and billing information
            conversations:read: Read your conversations and their messages
            conversations:write: Start conversations and send messages on your behalf
            documents:read: Read your documents library
            documents:write: Upload and manage documents in your library
            memory:read: Read what the assistant remembers about you
            memory:write: Correct or delete what the assistant remembers
            schedules:read: View your scheduled tasks
            schedules:write: Create and manage scheduled tasks
            tables:read: Read your tables and their rows
            tables:write: Create tables and add, edit, or delete rows

````