# search_events

Behavior, inputs, outputs and permissions for search_events.

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

This reference is generated from the published tool contract.

## Behavior and boundaries

Searches events in an interval of at most 744 elapsed hours (31 times 24 hours) across selected calendars and returns the matching ones in the same shape as list_events, including editBlockedReason when editing is unavailable. It searches the same text this assistant is allowed to see at its detail level: on a busy-only calendar the title is already a placeholder, so a search cannot match a hidden title, and the absence of a hit proves nothing about what is hidden. Locations and participants are not searched. `matched` and `truncated` describe the search itself: a truncated result is not proof that nothing else matches. All words must occur, in any order.

## 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"
      }
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "start": {
      "type": "string",
      "description": "Inclusive ISO 8601 date-time."
    },
    "end": {
      "type": "string",
      "description": "Exclusive ISO 8601 date-time, at most 744 elapsed hours after start. Split longer periods into consecutive windows; daylight-saving changes affect elapsed duration."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "timeZone": {
      "description": "User-confirmed IANA timezone for CalDAV all-day and floating times, e.g. Europe/Berlin.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "required": [
    "calendarIds",
    "query",
    "start",
    "end"
  ],
  "additionalProperties": false
}
```

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "termine": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "eventId": {
            "type": "string"
          },
          "calendarId": {
            "type": "string"
          },
          "occurrenceId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "coordinates": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            }
          },
          "virtualLocations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "uri": {
                  "type": "string"
                }
              },
              "required": [
                "uri"
              ],
              "additionalProperties": false
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "rel": {
                  "type": "string"
                }
              },
              "required": [
                "href"
              ],
              "additionalProperties": false
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "color": {
            "type": "string"
          },
          "start": {
            "type": "string"
          },
          "timeZone": {
            "type": "string"
          },
          "duration": {
            "type": "string"
          },
          "showWithoutTime": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "tentative",
              "cancelled"
            ]
          },
          "freeBusyStatus": {
            "type": "string",
            "enum": [
              "free",
              "busy"
            ]
          },
          "canRespond": {
            "type": "boolean",
            "description": "Whether this assistant may respond, subject to a fresh provider check."
          },
          "editBlockedReason": {
            "description": "Why editing is unavailable. Only calendar_read_only means the calendar is read-only; unknown means no verified reason.",
            "type": "string",
            "enum": [
              "calendar_read_only",
              "access_denied",
              "recurring_event",
              "not_organizer",
              "guests_or_scheduling",
              "conference",
              "managed_copy",
              "version_unavailable",
              "unknown"
            ]
          },
          "canEdit": {
            "type": "boolean",
            "description": "Whether this assistant may edit or delete, subject to a fresh provider check."
          },
          "responseStatus": {
            "type": "string",
            "enum": [
              "needs-action",
              "accepted",
              "declined",
              "tentative"
            ]
          },
          "privacy": {
            "type": "string",
            "enum": [
              "public",
              "private",
              "secret"
            ]
          },
          "alerts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "offset": {
                  "type": "string"
                },
                "action": {
                  "type": "string",
                  "enum": [
                    "display",
                    "email"
                  ]
                }
              },
              "required": [
                "offset"
              ],
              "additionalProperties": false
            }
          },
          "workingLocation": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "home",
                  "office",
                  "custom"
                ]
              },
              "label": {
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "eventId",
          "calendarId",
          "occurrenceId",
          "title",
          "start",
          "duration",
          "showWithoutTime",
          "status",
          "freeBusyStatus",
          "canRespond",
          "canEdit"
        ],
        "additionalProperties": false
      }
    },
    "matched": {
      "type": "number"
    },
    "truncated": {
      "type": "boolean"
    },
    "searchedFields": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "ok",
    "termine",
    "matched",
    "truncated",
    "searchedFields"
  ],
  "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/)