# search_events

Verhalten, Eingaben, Ausgaben und Freigaben für search_events.

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

Diese Referenz wird aus dem veröffentlichten Werkzeugvertrag erzeugt. Feldnamen und normative Beschreibungen im Schema sind Englisch.

## Verhalten und Grenzen

Sucht Termine in einem begrenzten Zeitraum über ausgewählte Kalender und gibt die Treffer in derselben Form wie list_events zurück. Gesucht wird in genau dem Text, den dieser Assistent auf seiner Detailstufe sehen darf: Bei einem Kalender mit Busy-only ist der Titel bereits ein Platzhalter, eine Suche kann also keinen verborgenen Titel treffen, und ein ausbleibender Treffer beweist nichts über das Verborgene. Orte und Teilnehmer werden nicht durchsucht. `matched` und `truncated` beschreiben die Suche selbst: Ein gekapptes Ergebnis ist kein Beweis, dass nichts weiter passt. Alle Wörter müssen vorkommen, in beliebiger Reihenfolge. Wie list_events enthält jeder nicht bearbeitbare Termin editBlockedReason. Pro Aufruf sind höchstens 744 verstrichene Stunden (31 × 24 Stunden) erlaubt. Zeitumstellungen berücksichtigen und längere Zeiträume in aufeinanderfolgende Fenster teilen. Bei einem Eingabefehler die Zeitgrenzen korrigieren und erneut abfragen.

## Berechtigungen

Freigegebene Scopes, Konten, Kalender und Sichtbarkeitsregeln begrenzen den Zugriff. Ein Workspace-Admin erhält dadurch keinen pauschalen Zugriff auf fremde Konten.

`calendar:read`

[Freigaben und Grenzen](https://docs.getridian.com/de/developers/authentication/)

## Eingabe

```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
}
```

## Ausgabe

```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
}
```

## Fehler und Wiederholungen

Prüfe das Werkzeugergebnis auf Fehler. Wiederhole Schreiboperationen nicht blind nach einem Timeout. Prüfe zuerst den aktuellen Ressourcen- oder Sendestatus.

[Fehlerbehandlung](https://docs.getridian.com/de/developers/errors/)