When people are free together

calendar.free_time.find

GET/api/v1/households/{household_id}/queries/calendar.free_time.find

Query
Rigel runs it

Spans of at least min_minutes between from and to (to excluded, at most 62 days) when none of the listed people is busy, in order. A person is busy during events that involve them, events on their own calendar, and busy-only blocks on it. Tentative events count as busy. All-day events count only when they are a trip or busy. within_hours (in the household's zone) clips each day to, say, 08:00 to 20:00. Errors: invalid_time_range, range_too_long.

Parameters#

When people are free together: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`person_ids`queryarray of stringsrequired	Everyone who has to be free. 1 to 20 items
`from`querystringrequired	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.
`to`querystringrequired	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.
`min_minutes`queryintegerrequired	The shortest span worth returning. 5 to 1,440
`within_hours`queryobjectoptional	Only count time between these hours each day, in the household's zone, such as 08:00 to 20:00.

Response#

200 The answer.

When people are free together: response fields
Field	Description
`items`array of objectsrequired
`items[].starts_at`stringrequired	ISO 8601 with the household's offset.
`items[].ends_at`stringrequired	No description.
`items[].when`stringrequired	In words, such as "Tue, Nov 11, 3:30–5pm".
`items[].minutes`integerrequired	How long the span is.

Errors#

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

When people are free together: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	`invalid_time_range`	Described above.
`409`	`range_too_long`	Described above.

Examples#

No call has been recorded for this operation yet, so this example is built from its schema. The values are placeholders.

Built from the schema

Not recorded from a real call: the fields are filled in from the schema, so the values are placeholders.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/queries/calendar.free_time.find?person_ids=per_01K9BKNGK0ENW3AHRZ6DMV29GQ&from=2026-11-11&to=2026-11-11&min_minutes=5' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/queries/calendar.free_time.find?person_ids=per_01K9BKNGK0ENW3AHRZ6DMV29GQ&from=2026-11-11&to=2026-11-11&min_minutes=5", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/queries/calendar.free_time.find?person_ids=per_01K9BKNGK0ENW3AHRZ6DMV29GQ&from=2026-11-11&to=2026-11-11&min_minutes=5 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_01K9BKNGK0ENW3AHRZ6DMV29GQ

{
  "items": [
    {
      "starts_at": "example",
      "ends_at": "example",
      "when": "Tue, Nov 11, 3:30–5pm",
      "minutes": 1
    }
  ]
}

For Rigel#

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