Items

List event occurrences

Returns the events that overlap a time window, with each recurring event expanded into one entry per occurrence. Marfa computes occurrences when you read them and doesn't store them.

GET
/occurrences

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Query parameters

from*string

A date-time needs seconds and a zone or offset; a date is UTC midnight. An event overlaps if it starts before to and ends after this. Its end is ends_at, else start plus duration. A whole-day event fills whole days of its timezone or UTC.

to*string

Window end, read as from is. The window can span at most 400 days. An event with no length is in the window if it starts at or after from and before this time.

type?string

Only return events of this type, or of the event types a wildcard matches. Names one type.

Response body

About errors

Returns occurrences ordered by start time. A recurring event gives an entry per occurrence, with series_id. A stored exception replaces its occurrence and carries replaces. A rule Marfa can't read or fully apply is listed in series_errors, and expansion_incomplete is true if an expansion didn't finish.

application/json
  1. response

The occurrences in a time window, with any rules Marfa couldn't apply.

data*array<>

The occurrences that overlap the window, by start time.

next_cursor*|

Always null: Marfa returns every occurrence in the window in one page.

window*

The window you asked for, in UTC.

scan*

How many rules Marfa couldn't apply or finish.

series_errors?array<>

One entry per failure found in a recurrence rule, such as a line Marfa can't read or a timezone that doesn't resolve. One event can have several entries and still appear in data. Absent when there were none.

series_errors_truncated?boolean

true when series_errors stops at 500 entries and leaves failures out. scan.series_errors has the total. Absent otherwise.

expansion_incomplete?boolean

true when a series didn't finish expanding, so data may be missing occurrences; scan.series_unexpanded counts them. If a series has too many in the window, narrow the window; else narrow by type or fix the rules. Absent otherwise.

  • missing_required_field: from or to is missing.
  • unknown_type: type isn't registered.
  • validation_error: a time is unreadable, to isn't after from, the window is over 400 days, type is malformed, or the window holds more than 5,000 occurrences. Then details has max_occurrences, or max_days for the window.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • type_not_permitted: your credential reaches no type, or type is a registered type you can't read with none readable under it.
application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X GET 'http://localhost:8600/occurrences?from=string&to=string'
About errors
{  "data": [    {      "starts_at": "2026-10-07T08:00:00.000Z",      "ends_at": "2026-10-07T09:00:00.000Z",      "item": {        "id": "01a1012b-8d07-7a13-b5c4-61e0f39a2d78",        "type": "core.event",        "state": "active",        "tier": "library",        "created_at": "2026-09-01T08:00:00.000Z",        "updated_at": "2026-09-01T08:00:00.000Z",        "last_activity_at": "2026-09-01T08:00:00.000Z",        "occurred_at": "2026-10-07T08:00:00.000Z",        "source": "calendar",        "version": 1,        "schema_version": 1,        "trashed_at": null,        "read_only": false,        "properties": {          "title": "Dentist",          "starts_at": "2026-10-07T08:00:00.000Z",          "ends_at": "2026-10-07T09:00:00.000Z"        }      }    },    {      "starts_at": "2026-10-09T10:00:00.000Z",      "ends_at": "2026-10-09T10:30:00.000Z",      "item": {        "id": "01a1012b-5e31-7c42-9a6e-2d4f8b1c7e50",        "type": "core.event",        "state": "active",        "tier": "library",        "created_at": "2026-09-01T08:00:00.000Z",        "updated_at": "2026-09-01T08:00:00.000Z",        "last_activity_at": "2026-09-01T08:00:00.000Z",        "occurred_at": "2026-09-04T10:00:00.000Z",        "source": "calendar",        "version": 1,        "schema_version": 1,        "trashed_at": null,        "read_only": false,        "properties": {          "title": "Team review",          "starts_at": "2026-09-04T10:00:00.000Z",          "ends_at": "2026-09-04T10:30:00.000Z",          "recurrence": [            "RRULE:FREQ=WEEKLY;BYDAY=FR"          ]        }      },      "series_id": "01a1012b-5e31-7c42-9a6e-2d4f8b1c7e50"    }  ],  "next_cursor": null,  "window": {    "from": "2026-10-05T00:00:00.000Z",    "to": "2026-10-12T00:00:00.000Z"  },  "scan": {    "series_errors": 0,    "series_unexpanded": 0  }}