# find_available_times

Behavior, inputs, outputs and permissions for find_available_times.

Source: https://docs.getridian.com/developers/tools/find_available_times/
Language: en
Reviewed: 2026-09-20

This reference is generated from the published tool contract.

## Behavior and boundaries

Finds UTC windows where all selected calendars are free. The request is bounded to 20 calendars and 31 days and transports no event titles, descriptions, or attendees. Constrain start and end to the hours you actually want considered.

## Permissions

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

`calendar:read`

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

## Input

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "calendarIds": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start": {
      "type": "string",
      "description": "Inclusive ISO 8601 date-time."
    },
    "end": {
      "type": "string",
      "description": "Exclusive ISO 8601 date-time."
    },
    "timeZone": {
      "description": "User-confirmed IANA timezone for CalDAV all-day and floating times, e.g. Europe/Berlin. Supply it for CalDAV; ask the user if unknown. Does not change absolute event timestamps.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "durationMinutes": {
      "type": "integer",
      "minimum": 5,
      "maximum": 1440
    }
  },
  "required": [
    "calendarIds",
    "start",
    "end",
    "durationMinutes"
  ],
  "additionalProperties": false
}
```

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "windows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          }
        },
        "required": [
          "start",
          "end"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "ok",
    "windows"
  ],
  "additionalProperties": false
}
```

## Errors and retries

Check the tool result for errors. Do not blindly retry writes after a timeout. Check the calendar state first.

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