Skip to content
Rigel docs
Open Rigel

What's happening in a date range

calendar.occurrence.list

GET/api/v1/households/{household_id}/queries/calendar.occurrence.list

  • Query
  • Rigel runs it

Every occurrence between from and to (to is excluded, at most 400 days), with repeating events expanded and cancelled occurrences left out, in order. A bare date means midnight at the start of that day in the household's zone. Calendars hidden in settings are left out unless include_hidden or listed in calendar_ids. person_ids matches events that involve one of those people or are on their own calendar. Errors: invalid_time_range, range_too_long.

Parameters#

What's happening in a date range: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

fromquerystringrequired

A date (YYYY-MM-DD, meaning midnight at the start of that day in the household's zone) or an ISO 8601 date-time. Date-times without an offset are in the household's zone.

toquerystringrequired

A date (YYYY-MM-DD, meaning midnight at the start of that day in the household's zone) or an ISO 8601 date-time. Date-times without an offset are in the household's zone.

calendar_idsqueryarray of stringsoptional

Only these calendars (hidden ones included).

at most 50 items
person_idsqueryarray of stringsoptional

Only events involving one of these people, or on their calendar.

at most 50 items
kindsqueryarray, each one of: event, appointment, activity, chore, meal, trip, birthday, holiday, reminder, busyoptional

Only these kinds of event.

at most 10 items
include_hiddenquerybooleanoptional

Also include calendars that are hidden by default. Defaults to false.

Response#

200 The answer.

What's happening in a date range: response fields
FieldDescription
itemsarray of objectsrequired
items[].event_idstringrequired

A calendar event ID, such as evt_01JC0000000000000000000000.

items[].occurrence_startstringrequired

The occurrence's original start in the event's zone. Pass it to the occurrence commands.

items[].titlestringrequired

The title, with this occurrence's change applied.

items[].starts_atstring or nullrequired

ISO 8601 with the household's offset; null for all-day.

items[].ends_atstring or nullrequiredNo description.
items[].start_datestring or nullrequired

YYYY-MM-DD; null for timed events.

items[].end_datestring or nullrequired

The last day, inclusive; null for timed events.

items[].is_all_daybooleanrequiredNo description.
items[].whenstringrequired

In words, such as "Tue, Nov 11, 3:30–4:30pm".

items[].kindone of: event, appointment, activity, chore, meal, trip, birthday, holiday, reminder, busyrequiredNo description.
items[].statusone of: confirmed, tentativerequiredNo description.
items[].calendarobjectrequired
items[].calendar.idstringrequired

A calendar ID, such as cal_01JC0000000000000000000000.

items[].calendar.namestringrequiredNo description.
items[].calendar.colorone of: calendar-1, calendar-2, calendar-3, calendar-4, calendar-5, calendar-6, calendar-7, calendar-8required

The calendar's color token.

items[].peoplearray of objectsrequired
items[].people[].idstringrequired

A person ID, such as per_01JC0000000000000000000000.

items[].people[].namestringrequiredNo description.
items[].locationstring or nullrequiredNo description.
items[].sourceobject or nullrequired

The app that owns the event, or null when it's the calendar's own.

items[].source.appone of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenancerequired

An app: meals (meal planning), recipes, shopping, inventory, calendar, email, tasks, documents, chat, or maintenance (home maintenance).

items[].source.record_idstringrequired

The owning app's record.

items[].is_busy_onlybooleanrequired

Its calendar stores only that the time is busy.

items[].is_recurringbooleanrequired

It's part of a repeating event.

items[].is_changedbooleanrequired

This occurrence was changed from the rule (moved, retitled, or an extra date).

truncatedbooleanrequired

There were more than 1,000 occurrences; ask for a shorter range.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

What's happening in a date range: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404not_foundThe household doesn't exist, or you aren't a member of it.
409invalid_time_rangeDescribed above.
409range_too_longDescribed above.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

What's on the calendar for two weeks

A repeating event shows once for each time it happens. occurrence_start identifies one for changes.

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSJA352HEQ35DZTQBT7T

{
  "items": [
    {
      "event_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "occurrence_start": "2026-11-10T17:00:00",
      "title": "Soccer practice",
      "starts_at": "2026-11-10T17:00:00-06:00",
      "ends_at": "2026-11-10T18:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Tue, Nov 10, 5–6pm",
      "kind": "activity",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
        "name": "Nia and Theo",
        "color": "calendar-5"
      },
      "people": [
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": "Riverside Park",
      "source": null,
      "is_busy_only": false,
      "is_recurring": true,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSHWH4PNSMGCX1WKFWDT",
      "occurrence_start": "2026-11-12T15:30:00",
      "title": "Nia's dentist",
      "starts_at": "2026-11-12T15:30:00-06:00",
      "ends_at": "2026-11-12T16:15:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Thu, Nov 12, 3:30–4:15pm",
      "kind": "appointment",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CS6RESEHY2KVBGF3JX5Q",
        "name": "Family",
        "color": "calendar-1"
      },
      "people": [
        {
          "id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
          "name": "Ada Okafor"
        },
        {
          "id": "per_01M6V9CS79TMYHDAM7FTA9ZK3Z",
          "name": "Nia"
        }
      ],
      "location": "Lakeview Dental",
      "source": null,
      "is_busy_only": false,
      "is_recurring": false,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSJ21CBFYER5ACBGBM1N",
      "occurrence_start": "2026-11-13T19:00:00",
      "title": "Family movie night",
      "starts_at": "2026-11-13T19:00:00-06:00",
      "ends_at": "2026-11-13T21:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Fri, Nov 13, 7–9pm",
      "kind": "event",
      "status": "tentative",
      "calendar": {
        "id": "cal_01M6V9CS6RESEHY2KVBGF3JX5Q",
        "name": "Family",
        "color": "calendar-1"
      },
      "people": [
        {
          "id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
          "name": "Ada Okafor"
        },
        {
          "id": "per_01M6V9CS744BQQH188FS6CXY9W",
          "name": "Ben Okafor"
        },
        {
          "id": "per_01M6V9CS79TMYHDAM7FTA9ZK3Z",
          "name": "Nia"
        },
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": null,
      "source": null,
      "is_busy_only": false,
      "is_recurring": false,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "occurrence_start": "2026-11-17T17:00:00",
      "title": "Soccer practice",
      "starts_at": "2026-11-17T17:00:00-06:00",
      "ends_at": "2026-11-17T18:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Tue, Nov 17, 5–6pm",
      "kind": "activity",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
        "name": "Nia and Theo",
        "color": "calendar-5"
      },
      "people": [
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": "Riverside Park",
      "source": null,
      "is_busy_only": false,
      "is_recurring": true,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSJ8BBY7SAS3VQTA0FCZ",
      "occurrence_start": "2026-11-18T18:00:00",
      "title": "Parent-teacher conferences",
      "starts_at": "2026-11-18T18:00:00-06:00",
      "ends_at": "2026-11-18T19:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Wed, Nov 18, 6–7pm",
      "kind": "event",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CS6RESEHY2KVBGF3JX5Q",
        "name": "Family",
        "color": "calendar-1"
      },
      "people": [],
      "location": null,
      "source": null,
      "is_busy_only": false,
      "is_recurring": false,
      "is_changed": false
    }
  ],
  "truncated": false
}

Only appointments and activities

Repeat kinds for more than one.

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23&kinds=appointment&kinds=activity' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23&kinds=appointment&kinds=activity", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23&kinds=appointment&kinds=activity HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSJJ0TE5HHXYDWNKJ8FS

{
  "items": [
    {
      "event_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "occurrence_start": "2026-11-10T17:00:00",
      "title": "Soccer practice",
      "starts_at": "2026-11-10T17:00:00-06:00",
      "ends_at": "2026-11-10T18:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Tue, Nov 10, 5–6pm",
      "kind": "activity",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
        "name": "Nia and Theo",
        "color": "calendar-5"
      },
      "people": [
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": "Riverside Park",
      "source": null,
      "is_busy_only": false,
      "is_recurring": true,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSHWH4PNSMGCX1WKFWDT",
      "occurrence_start": "2026-11-12T15:30:00",
      "title": "Nia's dentist",
      "starts_at": "2026-11-12T15:30:00-06:00",
      "ends_at": "2026-11-12T16:15:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Thu, Nov 12, 3:30–4:15pm",
      "kind": "appointment",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CS6RESEHY2KVBGF3JX5Q",
        "name": "Family",
        "color": "calendar-1"
      },
      "people": [
        {
          "id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
          "name": "Ada Okafor"
        },
        {
          "id": "per_01M6V9CS79TMYHDAM7FTA9ZK3Z",
          "name": "Nia"
        }
      ],
      "location": "Lakeview Dental",
      "source": null,
      "is_busy_only": false,
      "is_recurring": false,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "occurrence_start": "2026-11-17T17:00:00",
      "title": "Soccer practice",
      "starts_at": "2026-11-17T17:00:00-06:00",
      "ends_at": "2026-11-17T18:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Tue, Nov 17, 5–6pm",
      "kind": "activity",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
        "name": "Nia and Theo",
        "color": "calendar-5"
      },
      "people": [
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": "Riverside Park",
      "source": null,
      "is_busy_only": false,
      "is_recurring": true,
      "is_changed": false
    }
  ],
  "truncated": false
}

What Nia and Theo are doing

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23&person_ids=per_01M6V9CS79TMYHDAM7FTA9ZK3Z&person_ids=per_01M6V9CS7CDAEP5VDA5T8R9TG6' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23&person_ids=per_01M6V9CS79TMYHDAM7FTA9ZK3Z&person_ids=per_01M6V9CS7CDAEP5VDA5T8R9TG6", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/calendar.occurrence.list?from=2026-11-09&to=2026-11-23&person_ids=per_01M6V9CS79TMYHDAM7FTA9ZK3Z&person_ids=per_01M6V9CS7CDAEP5VDA5T8R9TG6 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSJM4Y1NSDZ5M00P95HD

{
  "items": [
    {
      "event_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "occurrence_start": "2026-11-10T17:00:00",
      "title": "Soccer practice",
      "starts_at": "2026-11-10T17:00:00-06:00",
      "ends_at": "2026-11-10T18:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Tue, Nov 10, 5–6pm",
      "kind": "activity",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
        "name": "Nia and Theo",
        "color": "calendar-5"
      },
      "people": [
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": "Riverside Park",
      "source": null,
      "is_busy_only": false,
      "is_recurring": true,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSHWH4PNSMGCX1WKFWDT",
      "occurrence_start": "2026-11-12T15:30:00",
      "title": "Nia's dentist",
      "starts_at": "2026-11-12T15:30:00-06:00",
      "ends_at": "2026-11-12T16:15:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Thu, Nov 12, 3:30–4:15pm",
      "kind": "appointment",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CS6RESEHY2KVBGF3JX5Q",
        "name": "Family",
        "color": "calendar-1"
      },
      "people": [
        {
          "id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
          "name": "Ada Okafor"
        },
        {
          "id": "per_01M6V9CS79TMYHDAM7FTA9ZK3Z",
          "name": "Nia"
        }
      ],
      "location": "Lakeview Dental",
      "source": null,
      "is_busy_only": false,
      "is_recurring": false,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSJ21CBFYER5ACBGBM1N",
      "occurrence_start": "2026-11-13T19:00:00",
      "title": "Family movie night",
      "starts_at": "2026-11-13T19:00:00-06:00",
      "ends_at": "2026-11-13T21:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Fri, Nov 13, 7–9pm",
      "kind": "event",
      "status": "tentative",
      "calendar": {
        "id": "cal_01M6V9CS6RESEHY2KVBGF3JX5Q",
        "name": "Family",
        "color": "calendar-1"
      },
      "people": [
        {
          "id": "per_01M6V9CS6RX26JK5KVYGRN22D2",
          "name": "Ada Okafor"
        },
        {
          "id": "per_01M6V9CS744BQQH188FS6CXY9W",
          "name": "Ben Okafor"
        },
        {
          "id": "per_01M6V9CS79TMYHDAM7FTA9ZK3Z",
          "name": "Nia"
        },
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": null,
      "source": null,
      "is_busy_only": false,
      "is_recurring": false,
      "is_changed": false
    },
    {
      "event_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "occurrence_start": "2026-11-17T17:00:00",
      "title": "Soccer practice",
      "starts_at": "2026-11-17T17:00:00-06:00",
      "ends_at": "2026-11-17T18:00:00-06:00",
      "start_date": null,
      "end_date": null,
      "is_all_day": false,
      "when": "Tue, Nov 17, 5–6pm",
      "kind": "activity",
      "status": "confirmed",
      "calendar": {
        "id": "cal_01M6V9CSHK7NNRTMZQSM1BFD1B",
        "name": "Nia and Theo",
        "color": "calendar-5"
      },
      "people": [
        {
          "id": "per_01M6V9CS7CDAEP5VDA5T8R9TG6",
          "name": "Theo"
        }
      ],
      "location": "Riverside Park",
      "source": null,
      "is_busy_only": false,
      "is_recurring": true,
      "is_changed": false
    }
  ],
  "truncated": false
}

For Rigel#

Rigel's tool for this query is calendar_occurrence_list. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel