GET /v1/schedules/{scheduleId}/occurrences/{occurrenceId} — occurrences.read

Read an occurrence

Greatwait

What Greatwait does, what a first successful result looks like, and which path to take to reach it.

Start here

Who the Greatwait alpha is for, how access works, what you bring, and what this release leaves out.

The invited alpha

The objects Greatwait works with, from organization and project down to a single delivery attempt, and how refusals are reported.

Concepts

What the curl, JavaScript and command-line quickstarts need first, the names they read, and the sequence they walk.

Before you begin

Reach a first delivered callback using only the Greatwait dashboard, from accepting your invitation to reading the delivery attempt.

Website quickstart

Connect an MCP client to Greatwait with OAuth or a scoped API key, and reach an observed callback.

Quickstart: MCP

Nine calls with curl and jq, from a clean shell to a delivery attempt you can read.

Quickstart: curl

The same nine calls through the published JavaScript SDK on plain Node, with every response parsed by its published schema.

Quickstart: JavaScript SDK

Install the published greatwait command and reach an observed callback one command at a time.

Quickstart: command line

Check that a callback really came from Greatwait, handle duplicates safely, answer with the right status, and rotate signing keys.

Verifying callbacks

Retry a create safely with an Idempotency-Key, avoid lost updates with ETag and If-Match, and make your receiver safe to call twice.

Idempotency and conditional writes

Choose between a fixed interval and a wall-clock cron schedule, pick a valid time zone, and know what happens when clocks change.

Recurrence and time zones

How Greatwait retries a callback, when it stops, what an ambiguous attempt means, and how to diagnose a delivery that did not succeed.

Failures and retries

Every operation an invited alpha member can call in production, with its request and the OpenAPI document it comes from.

API reference

The commands the invited alpha uses in the published @greatwait/cli 0.1.0-alpha.4, with usage, flags and exit codes.

Command-line reference

The tools the production MCP server lists for alpha work, what each needs, and the operations it keeps from agents.

MCP tools reference

Every refusal code the production API can return, its HTTP status, and whether repeating the request can succeed.

Problem codes

The bounds the alpha enforces today on payloads, delays, intervals, attempts, idempotency receipts and history.

Limits

A receiver in a project's test environment that fails on demand, for rehearsing delivery failures before your own receiver meets them.

Test sinks

Machine-readable entry points to these docs, and the MCP server an agent uses to act.

For agents

Create a data export

GET /v1/exports/{exportId} — exports.read

Read a data export

GET /v1/exports/{exportId}/parts — exports.part

Download a data export part

POST /v1/exports/{exportId}/cancel — exports.cancel

Cancel a data export

GET /__greatwait/version — meta.version

Read the deployed version

Read the workspace scaffold

Create a callback endpoint

List callback endpoints

GET /v1/endpoints/{endpointId} — endpoints.read

Read a callback endpoint

PUT /v1/endpoints/{endpointId} — endpoints.update

Update a callback endpoint

DELETE /v1/endpoints/{endpointId} — endpoints.disable

Disable a callback endpoint

POST /v1/endpoints/{endpointId}/signing-keys/rotate — endpoints.rotateSigningKey

Rotate a callback endpoint signing key

POST /v1/endpoints/{endpointId}/signing-keys/acknowledge — endpoints.acknowledgeSigningKeyRotation

Mark a signing-key server update done

GET /v1/endpoints/{endpointId}/signing-secret — endpoints.revealSigningSecret

Reveal a callback endpoint signing secret

POST /v1/endpoints/{endpointId}/enable — endpoints.enable

Enable a disabled callback endpoint

Create a test sink

List test sinks

GET /v1/test-sinks/{sinkId} — testsinks.read

Read a test sink

DELETE /v1/test-sinks/{sinkId} — testsinks.delete

Delete a test sink

PUT /v1/test-sinks/{sinkId}/program — testsinks.configure

Set a test sink behavior program

GET /v1/test-sinks/{sinkId}/deliveries — sinkdeliveries.list

List test sink deliveries

GET /v1/test-sinks/{sinkId}/deliveries/{deliveryRecordId} — sinkdeliveries.read

Read a test sink delivery

Read this credential's authority

POST /v1/credentials — credentials.create

Issue an API credential

List API credentials

GET /v1/credentials/{credentialId}/connection — credentials.connection

Read a credential's MCP connection

List the member's projects

Create a project

PATCH /v1/projects/{projectId} — projects.rename

Rename a project

DELETE /v1/projects/{projectId} — projects.delete

Delete an archived project

POST /v1/projects/{projectId}/archive — projects.archive

Archive or restore a project

List the member's connected applications

DELETE /v1/grants/{grantId} — grants.revoke

Disconnect an application

POST /v1/credentials/{credentialId}/rotate — credentials.rotate

Rotate an API credential

DELETE /v1/credentials/{credentialId} — credentials.revoke

Revoke an API credential

Create a schedule

List schedules

GET /v1/schedules/{scheduleId} — schedules.read

Read a schedule

PUT /v1/schedules/{scheduleId} — schedules.replace

Replace a schedule

DELETE /v1/schedules/{scheduleId} — schedules.cancel

Cancel a schedule

Forecast upcoming occurrences

Read terminal occurrence volume by day

GET /v1/timing/summary — timing.summary

Read rolling delivery timing

GET /v1/forecast/windows — forecast.windows

Forecast in the transitional window shape

GET /v1/schedules/{scheduleId}/occurrences — occurrences.list

List retained occurrences

List project executions

GET /v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts — attempts.list

List delivery attempts

GET /v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts/{attemptId} — attempts.read

Read a delivery attempt

POST /v1/schedules/{scheduleId}/occurrences/{occurrenceId}/redeliver — occurrences.redeliver

Redeliver an occurrence

POST /v1/schedules/{scheduleId}/pause — schedules.pause

Pause a schedule

POST /v1/schedules/{scheduleId}/resume — schedules.resume

Resume a schedule

POST /v1/schedules/{scheduleId}/archive — schedules.archive

Archive a schedule

Scoped API credential bound to one organization, project, and environment.

A signed-in member's session token. Unlike a credential or an access token it carries no project or environment, so a request using it must also send the two headers below.

Which environment of that project the request acts in: `test` or `live`.

Greatwait-Environment

Which project in the member's organization the request acts in. Checked against that organization; a project belonging to another answers exactly as one that does not exist.

Greatwait-Project

Generated from packages/contracts. Do not edit. This document describes the Greatwait API. NOTE: Zod refinements do not survive JSON Schema conversion, so a described schema is weaker than the one the service enforces — it accepts any string where the service requires a canonical IANA timezone or a real calendar date. Response schemas are described in output mode and request schemas in input mode. The contracts package is the validation authority in both directions.

Greatwait V1

Reports the service, environment, and build the request reached. Unauthenticated: it carries no customer data and is used by canaries and deployment smoke checks.

Reports the workspace layer this service occupies and the layers it may depend on. Exists so the architecture boundary is observable at runtime, not only at build time.

Replaces the caller organization's advisory execution budget and optional hard execution-spend cap for the current UTC month. Values are exact whole cents encoded as integer microdollars. The expected budget-policy revision prevents a stale editor overwriting a newer choice, and Idempotency-Key makes retrying one intent safe. Null turns that setting off. This command records desired state durably; billing.reconcile advances it to PostgreSQL, and reads remain pending until PostgreSQL confirms it. It never changes automatic top-up authority, purchases credit, or counts subscription payments as execution usage.

Reads the verified principal's authoritative execution-funding position, including available and reserved credit, amount owed, recurring project fees, the current UTC month's automatic-charge ceiling and its settled, pending and remaining gross authority, and bounded payment history. Manual purchases and project subscriptions are separately authorized and never consume the automatic ceiling. Pending gross charges include applicable tax; refunds never restore monthly automatic purchasing authority. Receipt and payment links are limited to supported provider-hosted HTTPS URLs.

Applies the exact unexpired automatic top-up preview a billing owner confirmed. Enable or expanded limits require this explicit approval; edit and disable fence queued unsubmitted work, while submitted or uncertain payments retain their original identity and UTC authorization month. Resume may clear only an authenticated payment-method failure and never an unresolved provider outcome. Applying a rule creates no charge; later low-balance work remains bounded by the approved fixed amount, one outstanding operation, cooldown, usage cap and gross monthly ceiling.

Previews one complete automatic execution-credit top-up rule without changing payment authority or contacting the payment provider. Enable and edit replace the fixed credit amount, usable-balance trigger and UTC-month gross ceiling together; disable and resume name those exact intents. The preview reports the current and proposed rule, whether authority expands, existing monthly commitments and separate recurring project fees. USD 10 below USD 2 within USD 50 is a suggested editable rule, not a platform maximum or target-balance refill.

Replaces the billing owner's exact calendar-month ceiling for automatic execution-credit charges, or turns automatic payment authority off with null. The expected revision prevents stale authority changes, and the Idempotency-Key makes retries converge. This command requires explicit agent approval because it changes payment authority. Tax and pending gross commitments consume the ceiling; manual purchases and project subscriptions do not. Refunds do not restore authority already used in that UTC month. USD 50 is the suggested editable default, not a platform maximum.

Confirms one exact manual execution-credit quote and creates or replays its durable payment operation. Billing-owner authority and explicit agent approval apply; the Idempotency-Key preserves one payment identity across retries. Manual funding stays outside the automatic-charge ceiling. A browser redirect never grants credit: only authenticated provider reconciliation can move the operation to paid and grant its exact execution credit once, while the operation reports provider-confirmed tax and gross when known.

Previews an execution-credit purchase of at least USD 10 without creating a provider payment or granting credit. The quote binds its exact credit and current funding revision; tax and gross remain null with calculated-at-checkout status until an idempotent confirmed purchase creates authenticated hosted Checkout. This manual purchase has separate authority and never consumes the automatic execution top-up ceiling.

Records an explicitly approved billing-owner request for operator review of unused purchased execution credit. It never submits a refund, cashes out credit or grants an MCP cash-out path; the Idempotency-Key preserves one request across retries. Trial credit has no cash value, provider submission remains an operator action, and any later refund does not restore automatic purchasing authority for the month.

Records an already-made external operator decision on a pending unused-credit refund request. Completion verifies an existing Stripe refund by authenticated provider read before applying the exact credit, tax and gross adjustment; it never creates a provider refund. Decline releases the reserved credit without contacting the provider. The Idempotency-Key makes either decision converge across retries.

Lists the verified principal's organization ledger in immutable sequence order. Each entry is one exact signed microdollar fact with safe attempt, lot, payment-operation and event references. Raw callback data, card data, internal causal keys and ledger detail have no field in the response. The opaque cursor is bound to the principal's organization, project and environment and cannot widen authority.

Lists the verified organization's durable billing notices with exact USD amounts, affected scope, payment state, a fixed same-page recovery path, and visible email delivery failure. Raw provider details, payment credentials, callback data and arbitrary URLs have no field.

Reads the USD 2.00 default low-credit threshold and optional-email choice. Critical email remains mandatory for owners and active billing-role members; addresses and contact management are absent.

Replaces the low-credit threshold and noncritical email choice at an expected revision. Critical email stays mandatory; idempotent retries converge and agents require explicit approval.

Creates a short-lived Stripe-hosted payment-method and invoice recovery session for the verified organization. It does not grant execution credit or additional project access.

Reads named included and subscribed project access, paid-through and grace deadlines, separate monthly fees, pending provider actions and desired/effective revisions.

Confirms the exact named-project quote and recurring commitment. Additional access activates only after authenticated successful provider payment; cancellation preserves paid-through access without a refund or renewal grace. Included transfer never subscribes the formerly included project. Retries retain the same operation and payment identity.

Previews one named project addition, paid-through cancellation or included-slot transfer without authorizing a charge. Quotes expire after five minutes and bind the current commercial revision. Amounts describe project fees; Stripe Checkout shows any applicable tax before confirmation.

Advances at most one due, already-authorized desired billing-policy revision for the caller's organization into PostgreSQL, then returns the same exact desired/effective summary as billing.summary. The command never changes the desired document. A transport failure is recorded for bounded retry and remains pending. Repeating the command may advance the next queued revision, so each call requires approval.

Reads the verified principal's organization-wide prepaid execution position from the authoritative PostgreSQL ledger. Desired and effective revisions remain distinct, and pending stays true until D1 records PostgreSQL confirmation. Amounts are exact integer microdollars encoded as decimal strings; currency is USD and scale is six. Reserved credit has already been committed to a logical attempt but is not yet a settled debit. A missing hard cap means the customer elected no execution spending cap, never zero room. Shadow mode records what enforcement would have done without charging or blocking, and the activation boundary prevents retroactive charges.

Reports the authority the presented credential carries: the project it acts in, which of that project's two environments, and the scopes the service will enforce for it. The answer comes entirely from the verified principal, so there is no parameter that could name another project and no way for the reply to describe anything but the caller itself. It requires a principal and no scope, because every value in it is a property of the credential being presented rather than of anything the credential may reach: a caller that could not read this could still act, and would simply be acting without being able to say where. A signed-in member is not accepted — a session's authority is an organization and it names its project per request, so there is no single answer to give one.

Lists the credentials issued for the caller's own project and environment, oldest first, one page at a time. The authority tuple comes from the verified principal, so there is no parameter that could name another project — a listing is the caller's own book or nothing. Revoked and rotated credentials stay in the listing and carry the fields that say so; a credential nobody can see is a credential nobody can audit. `limit` is bounded by the contract and `cursor` is the opaque value the previous page returned. No page carries a secret: the item is the read shape, which has no field one could be put in.

Issues an API credential bound to one project and environment, with scopes capped by the issuing member's current role. The full secret is in this response and in no other, is not recoverable afterwards, and there is deliberately no reveal endpoint. The value is the sixteen-character display prefix followed immediately by thirty-two more characters; the example below is a visible placeholder rather than that shape, because a realistic credential in a committed file is one the repository's own secret scanner refuses.

Revokes a credential immediately, with no overlap. The credential stops verifying on the next request and refuses with `credential_revoked`. The row survives its revocation so the credential's history remains answerable, and revoking a credential that is already revoked reports the original revocation rather than moving it. A credential belonging to another project is indistinguishable from one that does not exist. Some calls need more: credentials:administer is required as well when the target was not created by the caller, and the call is refused `scope_missing` without it.

Reads what a key this project issued should be able to do over MCP: the endpoint to point a client at, the discovery document beside it, the scopes fixed into the key when it was made, and the MCP tool names those scopes authorize. It returns no secret and cannot: the transient value is shown once at creation and is never sent here. The credential is addressed by identifier and re-resolved against the signed-in member's own project and environment, so a key belonging to another project answers exactly as one that does not exist. `state` distinguishes a key that still verifies from one that was revoked and one whose rotation overlap has run out, because a client configured with either fails identically and the remedies differ.

Replaces a credential with a new one and gives the original a deadline, so consumers can pick up the new secret before the old stops working. The replacement is a new credential with its own identifier and the same authority and scopes; the original keeps working until it expires, then refuses with `credential_expired` rather than `credential_revoked`. `overlapSeconds` may only shorten the window — the default is also the maximum — and zero retires the original immediately. The new secret is in this response and in no other. Some calls need more: credentials:administer is required as well when the target was not created by the caller, and the call is refused `scope_missing` without it.

Lists the caller's callback endpoints for exactly its own project and environment. The result is authoritative and metadata-only: no signing secret or sealed key material has a field in this shape.

Creates a reusable callback endpoint in the caller's project and environment. The destination must be HTTPS on effective port 443, contain no URL credentials or fragment, and resolve only to public unicast addresses. The endpoint is active and usable the moment it exists; there is nothing to verify. A disabled endpoint is never delivered to, and a schedule write naming one answers not_found, because disabling is terminal rather than a state to recover from. The per-endpoint secret is returned in this response and nowhere else. The 50-record safety ceiling includes disabled endpoints because they remain readable for audit.

Disables an endpoint immediately. It stays readable for audit but can no longer be updated or delivered to, and schedules pointed at it deliver nothing until `endpoints.enable` turns it back on. Repeating the disable is idempotent and does not write a second audit event, which is why it takes no precondition — the outcome does not depend on what else has changed.

Reads one callback endpoint from the caller's own project and environment. A well-formed identifier belonging to another authority is indistinguishable from an absent endpoint, and the response never contains secret material.

Replaces an endpoint's destination after applying the complete URL and DNS policy, and renames it when a name is given. Deliveries go to the new destination from the next one on. Disabled endpoints cannot be updated. Send If-Match with the version the endpoint was read at to be refused rather than overwrite a destination somebody else changed in the meantime.

Enables an endpoint that was disabled, so schedules pointed at it deliver again from the next occurrence on. Its address, name, signing keys and history are exactly as they were; nothing has to be created or re-pointed. Repeating the enable is idempotent and does not write a second audit event, so like `endpoints.disable` it takes no precondition. Somebody who disabled an endpoint by mistake, with many schedules pointed at it, gets it back with one call.

Records that a person has updated their server to accept the next signing key during the active overlap. This only marks the reminder done: it does not retire either key, shorten the overlap, or change which key signs new deliveries. Send If-Match with the version the endpoint was read at so an acknowledgement cannot be applied to a different rotation.

Creates the next endpoint signing key and selects it immediately for new deliveries while retaining the current key in the receiver acceptance set for a bounded overlap. The overlap defaults to and cannot exceed 24 hours. A second rotation is refused until the current overlap ends. The new secret is returned once and has no recovery operation, so a call whose answer was never read may have rotated a key nobody holds: read the endpoint and compare its signing keys before repeating one. Send If-Match with the version the endpoint was read at to be refused rather than rotate an endpoint that has changed since.

Reveals an endpoint's signing secret to a signed-in member: the value `endpoints.create` and `endpoints.rotateSigningKey` hand out once, readable again from the endpoint's own page. During a rotation both keys are returned, with the instant the overlap ends. Only a member session is accepted; an API credential or an OAuth token is refused, so an integration that needs the secret keeps the one the create or rotation that minted it returned. A disabled endpoint has nothing to reveal.

Starts an export for the authenticated project and environment. Records created or planned after cutoffAt are excluded; mutable fields have their current value when each part is read. Authority comes from the verified principal; no scope fields are accepted in the body.

Reads export progress inside the authenticated authority tuple.

Permanently cancels an export job. Repeating cancellation is safe and cancelled jobs cannot serve file parts.

Returns one bounded NDJSON file part. Cursors are opaque, authenticated, and bound to this export job.

Counts the occurrences this project and environment expect to fire, in epoch-aligned time buckets, with a latency-class split on every bucket and an optional customer partition-key breakdown. A recurring series contributes every instant it fires inside the window rather than only its next one, and `nextFireCount` reports how many of a bucket's occurrences are a schedule's next firing. The answer states its own freshness and is refused rather than shortened when a partition cannot complete it. It carries counts only: no schedule identifier, callback destination, payload or endpoint detail has a field in the response.

The same forecast in the window shape the legacy scheduler's autoscaler already parses, published under a dated version so a consumer can pin it. It exists for one migration and is expected to be withdrawn once that migration completes; `forecast.read` is the shape this product publishes. `byTenant` is the customer partition-key breakdown under its legacy name, and `count` is always the bucket total rather than the named subtotal.

Lists the applications this member has connected to their own account, newest first, across every project in their organization — because a person connects an application, not a project. Revoked connections stay in the listing with the instant and the reason they ended: a connection nobody can see is one nobody can audit. This is a signed-in member's view of their own delegations. An application holding a grant cannot read it, which is why the operation accepts no API credential and no access token, and why it is on no agent's tool list.

Disconnects one application, ending every token that grant ever issued — the access tokens and the refresh token together. The grant stays readable afterwards with the instant and the reason it ended. Only the member who granted it can disconnect it, and a grant belonging to somebody else answers exactly as one that does not exist.

Lists every retained occurrence in the verified principal's project and environment, newest first by planned instant with the occurrence identifier breaking millisecond ties. Optional endpoint, schedule, half-open date-range and outcome filters may be combined; the endpoint is resolved through the schedules that belong to the same authority. The opaque cursor belongs to this operation and the exact normalized filters that issued it, so it cannot be replayed under another view. Every page publishes the authoritative earliest retained instant for the caller's effective plan. Each item is metadata only: callback payloads, destinations, response bodies and signing material have no field in the response.

Stops customer access, execution and new purchases across the organization. Ordinary closure can be reversed for seven days; immediate erasure skips that window. Non-financial erasure completes within thirty days unless suspended by an operator legal hold. Financial records remain under the configured retention policy. An interrupted request resumes under the same generation; closure is acknowledged only after every configured scheduling shard is fenced.

Close the organization and request erasure

Reads the signed-in administrator's organization closure generation and progress, including the reversible window. It remains available during closure so the administrator can request recovery.

Restores access after every configured scheduling shard acknowledges the new generation. Immediate erasure and expired reversible windows cannot be restored. Recovery preserves each schedule's pause and lateness policy and does not reauthorize automatic top-up.

Cancel organization erasure during its reversible window

Lists the active and archived projects in the signed-in member's organization, with the environment kinds, lifecycle state, version and deletion-preview counts each one has. Active and archived rows both occupy a plan slot; deleted projects are absent. Archived rows are management targets rather than projects work may run inside, so a picker must not offer them as switch targets. The result is a display aid rather than an authorization control — naming a project on a later request re-resolves it against the member's own organization, and a project that is not theirs answers exactly as one that does not exist.

Creates a project in the signed-in member's organization, with both of its environments. This is the first call a new customer makes: an organization has no project until somebody makes one, and every other operation on this surface acts inside one. The `test` and `live` environments are provisioned with it in a single transaction rather than asked for, so a project is never observable in a half-provisioned state. The organization comes from the verified session and is never read from the request — a member who belongs to one organization cannot create a project in another. `PROJECT_LIST_LIMIT` bounds how many an organization may hold, and it is the same ceiling the listing publishes: a create that would take an organization past a list it can no longer return is refused rather than silently truncating a later read. A name is unique within the organization, compared ignoring case and surrounding or repeated spaces; a second project with a name already taken is refused with `state_conflict`, and the refusal says nothing about any other organization's names.

Permanently deletes an archived project and everything it owns immediately: schedules and encrypted payloads, occurrences and delivery attempts, endpoints and their signing keys, API credentials and their audit events, OAuth grants and tokens, test sinks, and control-plane projections. The operation is refused while the project is active and names archiving as the required first move. Its response reports the schedules, endpoints, keys and runs destroyed. Only organization administrators may perform it, and there is no restore operation.

Renames one project in the caller's own organization without changing its opaque identifier. Names remain unique within the organization ignoring ASCII case and surrounding or repeated whitespace. Send If-Match with the project's current version; a stale version is refused rather than silently overwriting somebody else's change. Members and administrators may rename because the change is cosmetic and reversible.

Archives or restores the caller's project. Archiving parks the complete project: no new occurrence is dispatched, while schedules, endpoints, keys, grants and retained history remain intact. Restoring clears that project-wide hold without rewriting any schedule; an occurrence whose instant passed while archived becomes due, matching schedule pause and resume. Only organization administrators may make this project-wide change.

Lists the caller's own schedules, oldest first, one page at a time. Archived schedules are left out: archiving is how a schedule leaves the working set, and a listing that still carried them would make the operation pointless. Give `endpoint` to keep the page to the schedules that deliver to that endpoint — the way back from a destination to everything pointed at it, which is what somebody who disabled or is about to move an endpoint needs to see. Items are schedules rather than schedules-with-occurrences, because a cross-partition listing is served from a projection that holds a summary; read a schedule to get its authoritative next occurrence. Every page states whether it is authoritative or projected.

Creates a schedule and returns it together with its first planned occurrence. Give exactly one of `at`, `delaySeconds`, `everySeconds` and `cron`. An optional `partitionKey` selects a fairness lane inside this project and environment; it is fixed after create. Add a verified `endpoint` to deliver each occurrence there; optional JSON `data` is encrypted before PostgreSQL persistence, placed in the signed callback, and returned as given by a schedule read. `at` and `delaySeconds` fire once; a delay is converted to an absolute instant when the request is accepted, so a schedule created either way reads back the same afterwards. `everySeconds` is a fixed duration and its first occurrence falls one interval after acceptance — it stays the same length across a daylight-saving change, and takes no timezone for that reason. `cron` is a wall clock: it is read against the IANA `timeZone` sent with it, `UTC` when none is, and the first occurrence is the first instant the expression names after acceptance. Where the clocks go forward and the wall time named does not exist that day, the occurrence falls at the first instant after the gap; where they go back and it happens twice, it falls once, at the earlier of the two. A recurring schedule is materialized one occurrence at a time: the next one is planned once the current one is due, so a read always shows one occurrence still to come. `lateness.policy` decides what happens when an occurrence reaches its first attempt after its planned instant: `skipAhead` never carries a recurring arrival across its next scheduled instant (and a shorter custom window may retire it earlier), while `catchUp` admits one arrival within `maxStalenessSeconds` even after later recurrence instants passed. A one-shot has no next recurrence, so either explicit policy uses its window and the default is `catchUp` with 24 hours; recurring schedules default to `skipAhead`, and a `catchUp` without an override has a one-interval window. A retry already in progress is exempt because it arrived and failed; its retry and give-up policy still decide the outcome. The organization, project and environment come from the verified principal; a body cannot name them, and the endpoint must belong to the same tuple, so a credential issued for one project can only ever create schedules in that project. Send an `Idempotency-Key` to make a retry safe: the identical request returns the schedule that key already created, marked `Idempotency-Replayed: true`, and creates nothing further; the same key with a different request is refused `idempotency_key_reused`. A replay reports the schedule **as it stands now**, not a frozen copy of the first response — if it was paused in between, the replay says so.

Cancels a schedule and settles its occurrence `cancelled`, releasing the timer. Terminal: a cancelled schedule cannot be resumed or replaced, and cancelling one that is already cancelled changes nothing and returns the same version. A cancel that races its own occurrence becoming due still wins — the occurrence settles cancelled and no work is delivered — which is why this is a refusal-free retry rather than a race a client has to reason about. The schedule stays readable; archive it to take it out of the listing.

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.

Replaces a schedule's definition, starting a new generation. Takes the same four ways of saying when as a create, so a one-shot can be replaced by a recurring definition and the other way round. An omitted callback endpoint/data pair preserves the stored callback; sending `data` alone replaces the encrypted data for the current endpoint, and sending `endpoint` selects a verified endpoint in the same authority tuple. The occurrence planned under the old definition is settled `skipped_stale` and can never fire unless it was already in flight, in which case its immutable attempt is allowed to settle honestly; a fresh occurrence is planned under the new definition, and the old definition's series stops advancing. `lateness` is resolved afresh against the replacement recurrence: omit it for that kind's default, or state `skipAhead`, `catchUp`, and an optional `maxStalenessSeconds` override. The policy applies only before an occurrence's first attempt; a retry already in progress remains on its retry and give-up ladder. Send `If-Match` with the version you read to make this conditional; without it the replace is unconditional and the last writer wins. A cancelled or completed schedule cannot be replaced. `partitionKey` is fixed when the schedule is created: omit it to preserve the stored value or echo that exact value in a GET → modify → PUT flow. Adding, changing, or clearing it is refused as `invalid_request` with `/partitionKey` identified. `latencyClass` remains derived from the replacement recurrence when the caller omits it.

Files a finished schedule away: it leaves the default listing and stays readable by identifier, carrying the instant it was archived. Only a cancelled or completed schedule can be archived — archiving is filing, not stopping, so cancel it first. Archiving an already archived schedule changes nothing and returns the same version.

Lists the retained occurrences of one schedule from its authoritative Scheduler Partition, ordered by durable creation instant and occurrence identifier so tied timestamps never duplicate or omit a row — oldest first unless `order=newest`, which walks from the most recent. A run that an edit replaced before it ran is left out; a run skipped because the previous one was still going is listed. The cursor is opaque, scoped to the verified principal's organization, project and environment, and to the order it was issued under. Each item is metadata only: callback payloads, destinations, response bodies and signing material have no field in the response.

Read an occurrence

Authorizations

Query Parameters

Response

200

400

401

403

404

409

429

503

​Authorizations

​Query Parameters

​Response

200

400

401

403

404

409

429

503

Authorizations

Query Parameters

Response