# find_booking_slots

Behavior, inputs, outputs and permissions for find_booking_slots.

Source: https://docs.getridian.com/developers/tools/find_booking_slots/
Language: en
Reviewed: 2026-10-06

This reference is generated from the published tool contract.

## Behavior and boundaries

Returns bookable start times of an appointment type between from and to (at most 31 days), as ISO times. Slots already respect availability, buffers, limits and the host's calendars. If incomplete is true, the calendar bookings are written to could not be reached and no slots are returned: do not book, ask the user to check the connection. A busy calendar that cannot be read is skipped, so a slot can overlap an event that exists only in that calendar. Appointment types bookable only via a funnel cannot be booked here.

## Permissions

Granted scopes, accounts, calendars and visibility rules limit access. Workspace administrators do not automatically gain access to other users’ accounts.

`bookings:read`

[Consent and boundaries](https://docs.getridian.com/developers/authentication/)

## Input

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "appointment_type_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "appointment_type_id from list_appointment_types."
    },
    "from": {
      "type": "string",
      "maxLength": 40
    },
    "to": {
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "appointment_type_id",
    "from",
    "to"
  ],
  "additionalProperties": false
}
```

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "slots": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "time_zone": {
      "type": [
        "string",
        "null"
      ]
    },
    "duration_minutes": {
      "type": [
        "number",
        "null"
      ]
    },
    "incomplete": {
      "type": "boolean"
    }
  },
  "required": [
    "slots",
    "time_zone",
    "duration_minutes",
    "incomplete"
  ],
  "additionalProperties": false
}
```

## Errors and retries

Check the tool result for errors. Do not blindly retry writes after a timeout. Check the current resource or send status first.

[Error handling](https://docs.getridian.com/developers/errors/)