---
title: "Read a schedule"
method: GET
path: "/v1/schedules/{scheduleId}"
---

# Read a schedule

`GET /v1/schedules/{scheduleId}`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/schedules/{scheduleId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Reads one schedule and its next occurrence from the partition that owns it. A schedule belonging to another organization, project or environment answers not_found rather than a refusal that would confirm it exists. The response carries the schedule's version as a strong ETag; send it back in `If-Match` to make a later write conditional on nothing having changed in between. The response carries the schedule's `data` when it has one, exactly as it was given; the listing leaves it off. Detail reads also include the custom JSON body; listings and mutation responses omit its content. HTTP settings expose ordinary values and configured secret markers, never secret values.

## Path parameters

- `scheduleId` string, required

## Response `200`

Read a schedule

- object
  - `occurrence` object, required
    - `attemptCount` integer, required
    - `firstAttemptLatenessMs` integer
    - `firstAttemptStartedAt` string
    - `timingEligibility` 'eligible' | 'customer_blocked' | 'platform_blocked'
    - `timingEligibilityReason` string
    - `timingPolicyVersion` string
    - `generation` integer, required
    - `id` string, required
    - `plannedFor` string, required
    - `schedule` string, required
    - `sequence` integer, required
    - `settledAt` string
    - `state` 'planned' | 'due' | 'dispatching' | 'retry_wait' | 'ambiguous' | 'succeeded' | 'terminal_failed' | 'cancelled' | 'skipped_stale', required
  - `schedule` object, required
    - `autoPauseAfterFailures` union: Consecutive failed runs before automatic pause: 1–100 or "never". Defaults to 5 on create; omission on replace preserves the setting. One-shot schedules are unaffected.
      - integer
      - 'never'
    - `consecutiveFailedRuns` integer
    - `autoPauseReason` object, nullable
      - `failedRuns` integer, required
      - `status` integer
      - `diagnostic` string, required
      - `pausedAt` string, required
    - `http` object
      - `method` 'POST' | 'PUT' | 'GET', required
      - `body` union, required
        - object
          - `mode` 'envelope', required
        - object
          - `mode` 'none', required
        - object
          - `mode` 'json', required
          - `value` Schema0 (unresolved $ref)
      - `headers` union[], required
        - union
          - object
            - `name` string, required
            - `secret` false, required
            - `value` string, required
          - object
            - `name` string, required
            - `secret` true, required
            - `configured` true, required
          - object
            - `name` string, required
            - `suppressed` true, required
    - `archivedAt` string
    - `data` Schema1 (unresolved $ref)
    - `createdAt` string, required
    - `delivery` object
      - `completion` 'response' | 'callback', required
      - `maxDurationSeconds` integer, required
      - `onOverlap` 'skip' | 'queue', required
    - `endpoint` string
    - `endpointUrl` string, uri
    - `generation` integer, required
    - `id` string, required
    - `latencyClass` 'realtime' | 'bulk', required
    - `lateness` object, required
      - `maxStalenessSeconds` integer
      - `policy` 'skipAhead' | 'catchUp', required
    - `name` string
    - `external_identifier` string: Host application identifier, matched exactly and case-sensitively; at most 256 UTF-8 bytes. Readable by schedule readers; do not include secrets.
    - `tags` string[]: Up to 16 distinct searchable tags. Omission preserves tags on replacement; [] clears them.
    - `partitionKey` string
    - `nextDueAt` string
    - `recurrence` union, required
      - object
        - `kind` 'at', required
      - object
        - `everySeconds` integer, required
        - `kind` 'every', required
      - object
        - `cron` string, required
        - `kind` 'cron', required
        - `timeZone` unknown, required
    - `status` 'active' | 'paused' | 'cancelled' | 'completed', required
    - `updatedAt` string, required
    - `version` integer, required

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing.
- `404`: Problem document. Possible codes at this status: not_found.
- `409`: Problem document. Possible codes at this status: project_archived.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)