Query free/busy
Returns busy intervals for a set of people and rooms over a time range.
Permission
The key must be granted calendar.freebusy.read
A key without it gets 403 insufficient_scope, with the missing permission named in details.
Returns busy intervals, never what the meetings are.
Request body
| Field | Type | Description |
|---|---|---|
attendees |
string[] | Addresses to check. Required unless resources is given. |
resources |
string[] | Room or equipment ids. Required unless attendees is given. |
start required |
RFC 3339 | |
end required |
RFC 3339 |
Request
curl https://api.veruapis.com/v1/freebusy \
-X POST \
-H "Authorization: Bearer vak_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"addresses": ["[email protected]", "[email protected]"],
"from": "2026-09-04T08:00:00Z",
"to": "2026-09-04T18:00:00Z"
}'Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.
Response
| Field | Type | Description |
|---|---|---|
attendees |
object[] | One entry per address asked about. Its fields are below. |
unknown_attendees |
string[] | Addresses outside this workspace. Not free — unknown, which is different, and treating them as free is how a meeting gets booked over someone. |
Each item in attendees
| Field | Type | Description |
|---|---|---|
email |
string | |
busy |
object[] | Intervals they are not free. Its fields are below. |
Each item in busy
| Field | Type | Description |
|---|---|---|
starts_at |
RFC 3339 | |
ends_at |
RFC 3339 |
{
"data": [
{
"address": "[email protected]",
"busy": [ { "from": "2026-09-04T13:00:00Z", "to": "2026-09-04T14:00:00Z" } ]
}
],
"meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}Busy intervals only, never what the person is doing. Someone with no shared availability comes back with an empty list rather than an error.
Every failure uses the same shape, with a stable string code you can branch on. See the error reference.
Related
- POST Create a calendar
- POST Create an event
- DELETE Delete a calendar
- DELETE Delete an event
- POST Find a time that works
- GET Get a calendar
- GET Get an event
- GET List events in a calendar
- GET List calendars
- GET List events
- POST Respond to an invitation
- PATCH Update a calendar
- PATCH Update an event