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.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
from*stringA 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*stringWindow 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?stringOnly return events of this type, or of the event types a wildcard matches. Names one type.
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- 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?booleantrue when series_errors stops at 500 entries and leaves failures out. scan.series_errors has the total. Absent otherwise.
expansion_incomplete?booleantrue 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:fromortois missing.unknown_type:typeisn't registered.validation_error: a time is unreadable,toisn't afterfrom, the window is over 400 days,typeis malformed, or the window holds more than 5,000 occurrences. Thendetailshasmax_occurrences, ormax_daysfor the window.
application/json- 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- response
An error response.
error*What went wrong.
type_not_permitted: your credential reaches no type, ortypeis a registered type you can't read with none readable under it.
application/json- 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- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X GET 'http://localhost:8600/occurrences?from=string&to=string'{ "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 }}