Read a calendar

A recurring event is one item with a recurrence rule, so a listing of items can't say what happens on a given day. List event occurrences can: Marfa works out each time an event happens when you ask, and stores none of them. A task can carry the same rule, which Marfa checks on a write and stores, but never unfolds: the listing answers events only. In the TypeScript example, marfa is a client made as the TypeScript SDK shows.

List a windowCopy anchor link

Name the start and end of the window:

marfa items occurrences --from 2026-10-12 --to 2026-10-26

Each entry has a starts_at, an ends_at where the event has one, and the item. An occurrence of a recurring event also carries a series_id, the id of the core.event whose recurrence rule made it:

{
  "starts_at": "2026-10-13T07:00:00.000Z",
  "ends_at": "2026-10-13T08:00:00.000Z",
  "series_id": "01a12313-ad0e-71cd-99b4-7a176c5a9f18"
}

The whole window comes in one page, in order of starts_at.

Write the boundsCopy anchor link

Marfa reads a bound as it reads any other time you send: a time with no zone, such as 2026-10-12T09:00:00, is UTC, a date with no time is its midnight in UTC, and an offset or Z is honored. A bound that isn't an ISO 8601 time, or names a date that doesn't exist such as 2026-02-30, is refused with 400 validation_error, and details.field says whether it was from or to.

A window spans at most 400 days, and Marfa refuses one with too many occurrences rather than trim it, so narrow the window.

Check the calendar is wholeCopy anchor link

If the answer carries expansion_incomplete: true, the calendar is missing something: series_errors names the series that couldn't be unfolded. Show the person that the calendar is incomplete rather than present it as whole.

The rules behind this guide are in the occurrences chapter of the contract.