---
title: "Forecast upcoming occurrences"
method: GET
path: "/v1/forecast"
---

# Forecast upcoming occurrences

`GET /v1/forecast`

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

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 freshness and explicit coverage. Clients sending X-Greatwait-Accept-Partial-Forecast: true receive bounded lower-bound counts when a book reaches a row, cell or recurrence-work bound, with coverage.complete false and the exact bounds reached. Without this capability header the previous refusal behavior remains safe for clients that only read totals. Unavailable or stale sources still refuse. Coverage identifies the selected recurring schedule range but never includes destinations, payload or endpoint detail.

## Query parameters

- `breakdown` 'none' | 'partitionKey'
- `bucketSeconds` integer
- `from` string
- `to` string

## Headers

- `X-Greatwait-Accept-Partial-Forecast` 'true'

## Response `200`

Forecast upcoming occurrences

- object
  - `coverage` object
    - `complete` boolean, required
    - `countMeaning` 'complete-total' | 'lower-bound', required
    - `projectedWindow` object, required
      - `from` string, required
      - `to` string, required
    - `completeThrough` string, required
    - `heads` object, required
      - `groupsRead` integer, required
      - `occurrencesCounted` integer, required
      - `complete` boolean, required
      - `selection` 'earliest bucket, latency class, partition key groups', required
      - `lastGroup` object
        - `start` string, required
        - `latencyClass` 'realtime' | 'bulk', required
        - `partitionKey` string, required
    - `recurring` object, required
      - `schedulesRead` integer, required
      - `populationComplete` boolean, required
      - `selection` 'oldest eligible active recurring schedules by createdAt and scheduleId', required
      - `firstScheduleId` string
      - `lastScheduleId` string
    - `work` object, required
      - `usedUnits` integer, required
      - `limitUnits` integer, required
    - `boundsReached` object[], required
      - `kind` 'head-cells' | 'recurring-series' | 'projection-work' | 'projection-cells', required
      - `limit` integer, required
  - `buckets` object[], required
    - `byLatencyClass` object, required
      - `bulk` integer, required
      - `realtime` integer, required
    - `byPartitionKey` object
    - `count` integer, required
    - `nextFireCount` integer, required
    - `otherPartitionKeyCount` integer
    - `start` string, required
  - `freshness` object, required
    - `asOf` string, required
    - `kind` 'projected', required
    - `lagSeconds` integer, required
  - `window` object, required
    - `bucketSeconds` integer, required
    - `from` string, required
    - `to` string, 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.
- `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)