---
title: "Read an occurrence"
method: GET
path: "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}"
---

# Read an occurrence

`GET /v1/schedules/{scheduleId}/occurrences/{occurrenceId}`

## 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}/occurrences/{occurrenceId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Reads one retained occurrence from the PostgreSQL authority that owns its schedule. Trusted first-outbound timing is optional for records that predate substantiation; when present, firstAttemptLatenessMs is signed and a negative value exposes an early-delivery defect rather than being clamped to zero. Timing eligibility states whether a customer restriction excluded the occurrence from the internal target cohort. An identifier outside the verified principal's organization, project or environment is indistinguishable from an absent occurrence.

## Path parameters

- `scheduleId` string, required
- `occurrenceId` string, required

## Response `200`

Read an occurrence

- object
  - `freshness` object, required
    - `kind` 'authoritative', required
  - `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

## 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)