List & Search Events

Query calendar events with keyword search, attendee filtering, date ranges, and pagination.

GET/api/access/calendar/eventsBearer Token

List/Search Events

Returns events with optional keyword search, attendee filtering, and pagination.

Query Parameters

Parameter	Type	Default	Description
q	string	—	Keyword search in title, description, location
attendees	string	—	Comma-separated attendee emails to filter by
calendarId	long	—	Filter by specific calendar ID
from	DateTimeOffset	Today	Start date (UTC or with timezone offset)
to	DateTimeOffset	from + 7 days	End date (UTC or with timezone offset)
limit	int	50	Max results (1–1000)
offset	int	0	Skip N results for pagination
includeCancelled	bool	false	Include cancelled events

Date Format Examples

Format	Example
UTC	2026-02-03T00:00:00Z
With timezone	2026-02-03T00:00:00-06:00 (CST)
Date only	2026-02-03 (treated as midnight UTC)

Smart Default Dates

When no from/to dates are provided and the token has timeframe restrictions, the API automatically calculates a sensible 7-day window within the allowed bounds. For example, a token that allows past 30 / future 30 days returns today ± 3 days by default.

Examples

GET /events 
GET /events?q=budget+review 
GET /events?q=meeting&calendarId=123 
GET /events?attendees=finance@example.com,cfo@example.com 
GET /events?q=standup&from=2026-02-01&to=2026-02-28&limit=100 
GET /events?from=2026-02-01T00:00:00-06:00&to=2026-02-28T23:59:59-06:00

Response 200 OK

{ 
  "events": [ 
    { 
      "id": "550e8400-e29b-41d4-a716-446655440000", 
      "title": "Team Meeting", 
      "description": "Weekly sync with the team", 
      "location": "Conference Room A", 
      "startUtc": "2026-02-05T14:00:00Z", 
      "endUtc": "2026-02-05T15:00:00Z", 
      "allDay": false, 
      "status": "confirmed", 
      "organizer": "organizer@example.com", 
      "attendees": [ 
        { 
          "email": "attendee@example.com", 
          "name": "John Doe", 
          "response": "accepted" 
        } 
      ], 
      "joinUrl": "https://meet.google.com/xxx-xxx-xxx", 
      "labels": ["important"], 
      "isRecurringEvent": false 
    } 
  ], 
  "accessInfo": "Results limited to time window: Last 30 days to next 30 days.", 
  "currentUserCalendarEmail": "user@example.com" 
}

Event Object Fields

Field	Type	Description
id	string (UUID)	Public event identifier
title	string	Event title/summary
description	string?	Event description
location	string?	Event location
startUtc	DateTime	Start time in UTC
endUtc	DateTime	End time in UTC
allDay	bool	Whether this is an all-day event
status	string	Event status: confirmed, tentative, cancelled
organizer	string?	Organizer's email address
attendees	Attendee[]	List of attendees
joinUrl	string?	Video conference join URL
labels	string[]	Event labels/tags
isRecurringEvent	bool	Whether this event is part of a recurring series

Attendee Object Fields

Field	Type	Description
email	string	Attendee's email address
name	string?	Attendee's display name
response	string?	Response status: accepted, declined, tentative, needsAction

GET/api/access/calendar/events/{eventId}Bearer Token

Get Event

Returns a single event by its public UUID.

Path Parameters

Parameter	Type	Description
eventId	string (UUID)	Public event ID

Response 200 OK

{ 
  "event": { 
    "id": "550e8400-e29b-41d4-a716-446655440000", 
    "title": "Team Meeting", 
    "description": "Weekly sync", 
    "location": "Conference Room A", 
    "startUtc": "2026-02-05T14:00:00Z", 
    "endUtc": "2026-02-05T15:00:00Z", 
    "allDay": false, 
    "status": "confirmed", 
    "organizer": "organizer@example.com", 
    "attendees": [ 
      { 
        "email": "attendee@example.com", 
        "name": "John Doe", 
        "response": "accepted" 
      } 
    ], 
    "joinUrl": "https://meet.google.com/xxx-xxx-xxx", 
    "labels": [], 
    "isRecurringEvent": false 
  }, 
  "accessInfo": "Results limited to time window: Last 30 days to next 30 days.", 
  "currentUserCalendarEmail": "user@example.com" 
}