---
title: "List upcoming moments"
method: GET
path: "/api/businesses/{business_id}/moments"
tags: ["businesses"]
---

# List upcoming moments

`GET /api/businesses/{business_id}/moments`

## Request

- Base URL: `https://api.mymarky.ai`
- URL: `https://api.mymarky.ai/api/businesses/{business_id}/moments`
- Auth: HTTP bearer

List the dated moments coming up for a business, and which are already covered.

Public holidays of the business's country (from its holiday setting, else
its timezone), curated marketing days, the first day of autumn/spring, and
the business's own `events` (set with update_business). Dates are on the
business's calendar; quote `date` and `weekday` as given.

Errors:
    401 authentication_required: API key or token is missing, invalid, or revoked.
    403 permission_denied: Your plan does not include API access, or this business is not in your org.
    404 resource_not_found: No business with that ID exists.
    422 validation_error: `days` is not between 1 and 90.
    429 rate_limit_exceeded: You sent too many requests this minute.

## Path parameters

- `business_id` string, required: A UUID identifier.

## Query parameters

- `days` integer: How many days ahead to look.

## Headers

- `Marky-Version` '2026-04-08' | '2026-07-17' | '2026-08-02' | '2026-08-04' | '2026-08-06'

## Response `200`

Successful Response

- UpcomingMomentsResponse
  - `timezone` string, required: IANA timezone of the business's calendar (dates are local to it).
  - `timezone_source` 'business' | 'unset_utc', required: `business`: the business's own setting. `unset_utc`: none saved, so dates are UTC.
  - `today_local` string, date, required: Today on the business's calendar.
  - `countries` string[], required: Whose public holidays are included: the business's holiday setting, else its timezone's country, else US.
  - `moments` Moment[], required: Upcoming moments by date. `type`: public (holiday), fun (marketing day or season start), event (the business's own). `days_until` 0 = today. `covered_post_ids`: posts already dated (pin or copy date) in the week up to it; empty = nothing planned. `estimated`: the date may move a day (Hijri calendar).
    - `name` string, required
    - `name_en` string, required
    - `date` string, date, required
    - `type` 'public' | 'fun' | 'event', required
    - `country` string, nullable, required
    - `days_until` integer, required
    - `estimated` boolean
    - `aliases` string[]
    - `covered_post_ids` string[]
    - `weekday` string, required: English weekday name, e.g. "Wednesday": Max quotes it, never computes it.

## Other responses

- `400`: Bad request — the input was malformed or otherwise invalid.
- `401`: Authentication failed — the API key is missing or invalid.
- `403`: Forbidden — the key is valid but may not access this resource.
- `404`: Not found — no resource matches the id in the path.
- `422`: Validation error — one or more fields failed validation.
- `429`: Rate limited — retry after the window resets (see Retry-After).
- `500`: Server error — something failed on our side; retry or quote X-Request-Id.

---

[API](https://skmtc.dev/mymarky/apis/marky-public-api.md) · [All operations](https://skmtc.dev/mymarky/apis/marky-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mymarky/apis/marky-public-api/revisions/25aeacae455c?raw)