Get Events

Get events from a Google Calendar with optional search query. Combines list and search functionality in one tool.

Overview

The Get Events tool retrieves events from your Google Calendar within a date range. You can:

• List all events in a date range (default: today to 30 days)
• Search for specific events using a text query
• Get comprehensive event details including attendees, conference links, recurrence, and more

This tool works with any calendar you have access to (use List Calendars to find calendar IDs).

Prerequisites

• A connected Google Account with OAuth authentication
• Google Calendar API enabled in your Google Cloud project
• Setup Guide

Usage

Basic Usage - List All Events

List all events in the default date range (today to 30 days):

{
  "tool": "google_calendar_Get_Events",
  "arguments": {}
}

Search for Specific Events

Search for events containing "dentist":

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "query": "dentist"
  }
}

Custom Date Range

Get events for a specific month:

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "start_date": "2024-02-01",
    "end_date": "2024-02-29"
  }
}

Search with Date Range

Find "meeting" events in January:

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "query": "meeting",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

Specific Calendar

Get events from a specific calendar (not primary):

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "calendar_id": "xyz123@group.calendar.google.com",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

Include Cancelled Events

Include cancelled/deleted events in results:

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "include_cancelled": true
  }
}

Limit Results

Get only next 10 events:

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "max_results": 10
  }
}

Input Parameters

Parameter	Type	Required	Default	Description
query	string	No	null	Text search query. Searches event summary and description. Leave empty to list all events.
start_date	string	No	today	Start of date range. Format: YYYY-MM-DD or ISO 8601 (e.g., 2024-01-15T10:00:00Z)
end_date	string	No	+30 days	End of date range. Format: YYYY-MM-DD or ISO 8601
calendar_id	string	No	"primary"	Calendar identifier. Use "primary" for main calendar or ID from List Calendars tool.
max_results	integer	No	250	Maximum events to return (1-2500)
single_events	boolean	No	true	Expand recurring events into individual instances. Set to false to see recurrence rules instead.
include_cancelled	boolean	No	false	Include cancelled/deleted events in results

Date Format Examples

• Simple date: "2024-01-15" (treated as start of day in UTC)
• Date with time and timezone: "2024-01-15T14:30:00-08:00"
• Date with time (UTC): "2024-01-15T22:30:00Z"

Response Format

Success Response

{
  "success": true,
  "events": [
    {
      "id": "abc123xyz",
      "calendar_id": "primary",
      "status": "confirmed",
      "summary": "Team Meeting",
      "description": "Weekly sync",
      "location": "Conference Room A",
      
      "start": "2024-01-15T14:00:00-08:00",
      "end": "2024-01-15T15:00:00-08:00",
      "start_datetime": "2024-01-15T14:00:00-08:00",
      "end_datetime": "2024-01-15T15:00:00-08:00",
      "start_timezone": "America/Los_Angeles",
      "end_timezone": "America/Los_Angeles",
      "all_day": false,
      
      "attendees": [
        {
          "email": "alice@example.com",
          "display_name": "Alice Smith",
          "response_status": "accepted",
          "optional": false,
          "organizer": false,
          "self": false,
          "comment": ""
        },
        {
          "email": "bob@example.com",
          "display_name": "Bob Jones",
          "response_status": "tentative",
          "optional": true,
          "organizer": false,
          "self": false,
          "comment": "Might be late"
        }
      ],
      "attendees_count": 2,
      
      "organizer": {
        "email": "you@gmail.com",
        "display_name": "You",
        "self": true
      },
      
      "creator": {
        "email": "you@gmail.com",
        "display_name": "You"
      },
      
      "conference": {
        "hangout_link": "https://meet.google.com/abc-defg-hij",
        "conference_solution": "Google Meet",
        "entry_points": [
          {
            "entryPointType": "video",
            "uri": "https://meet.google.com/abc-defg-hij"
          }
        ]
      },
      
      "recurrence": null,
      "recurring_event_id": null,
      
      "html_link": "https://www.google.com/calendar/event?eid=abc123xyz",
      "ical_uid": "abc123xyz@google.com",
      
      "visibility": "default",
      "transparency": "opaque",
      
      "reminders": {
        "use_default": false,
        "overrides": [
          {"method": "popup", "minutes": 10},
          {"method": "email", "minutes": 1440}
        ]
      },
      
      "created": "2024-01-01T10:00:00Z",
      "updated": "2024-01-10T15:30:00Z",
      
      "attachments": [],
      "attachments_count": 0
    }
  ],
  "total_count": 1,
  "calendar_id": "primary",
  "date_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "query": null,
  "summary": {
    "total": 1,
    "all_day_events": 0,
    "timed_events": 1,
    "cancelled": 0
  }
}

Response Fields

Event Object

Field	Type	Description
id	string	Unique event identifier
calendar_id	string	Which calendar this event belongs to
status	string	Event status: "confirmed", "tentative", or "cancelled"
summary	string	Event title/name
description	string	Event description/notes
location	string	Event location
Timing
start	string	Start date/time (formatted)
end	string	End date/time (formatted)
start_datetime	string	Start as ISO 8601 datetime (null for all-day events)
end_datetime	string	End as ISO 8601 datetime (null for all-day events)
start_timezone	string	Timezone of start time
end_timezone	string	Timezone of end time
all_day	boolean	Whether this is an all-day event
People
attendees	array	List of attendees with response status
attendees_count	integer	Number of attendees
organizer	object	Event organizer details
creator	object	Event creator details
Conference
conference	object	Conference/meeting details (Meet, Zoom, etc.)
hangout_link	string	Google Hangout/Meet link (legacy field)
Recurrence
recurrence	array	Recurrence rules (RRULE format) if not expanded
recurring_event_id	string	ID of master recurring event (if this is an instance)
Links
html_link	string	Link to view event in Google Calendar
ical_uid	string	iCalendar UID
Metadata
visibility	string	Event visibility: "default", "public", "private", "confidential"
transparency	string	Free/busy status: "opaque" (busy) or "transparent" (free)
reminders	object	Reminder settings
created	string	When event was created
updated	string	When event was last updated
attachments	array	File attachments
attachments_count	integer	Number of attachments

Attendee Response Status

• needsAction - No response yet (default)
• accepted - Accepted the invitation
• declined - Declined the invitation
• tentative - Maybe/tentative response

Event Status

• confirmed - Normal event (default)
• tentative - Tentative event
• cancelled - Cancelled/deleted (only returned if include_cancelled=true)

Use Cases

1. Check Your Week

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "start_date": "2024-01-15",
    "end_date": "2024-01-21",
    "max_results": 100
  }
}

2. Find All Meetings with a Person

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "query": "alice@example.com"
  }
}

Query searches both summary and attendee emails.

3. Get All Events in a Shared Calendar

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "calendar_id": "team@company.com"
  }
}

4. Find Conference Call Links

Search for "zoom" or "meet" to find video conference events:

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "query": "zoom"
  }
}

Then extract conference.hangout_link from results.

5. Recurring Events

Expanded (default):

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "query": "standup",
    "single_events": true
  }
}

Returns each occurrence as separate event.

Not expanded:

{
  "tool": "google_calendar_Get_Events",
  "arguments": {
    "query": "standup",
    "single_events": false
  }
}

Returns master event with recurrence rules.

Error Handling

Calendar API Not Enabled

Error:

{
  "error": "Google Calendar API is not enabled in your Google Cloud project..."
}

Solution: Follow Setup Guide to enable the API.

Invalid Date Format

Error:

{
  "error": "Invalid date format: '01/15/2024'. Use YYYY-MM-DD or ISO 8601 format..."
}

Solution: Use "2024-01-15" or "2024-01-15T10:00:00Z" format.

Date Range Error

Error:

{
  "error": "end_date must be after start_date"
}

Solution: Ensure end_date is chronologically after start_date.

Calendar Not Found

Error:

{
  "error": "Resource not found: Calendar not found"
}

Solution:

• Use List Calendars to find valid calendar IDs
• Ensure you have access to the calendar
• Use "primary" for your main calendar

No Events Found

If no events match your criteria, you'll get:

{
  "success": true,
  "events": [],
  "total_count": 0
}

This is not an error - it means no events match your search.

Tips

1. Default Behavior - Calling with no arguments gives you the next 30 days of events from your primary calendar
2. Search Tips - Query searches summary AND description, so be specific
3. All-Day Events - Check all_day field to distinguish from timed events
4. Recurring Events - Default expands recurring events. Set single_events=false to see recurrence rules
5. Conference Links - Check conference.hangout_link for Meet/Zoom URLs
6. Response Status - Use attendees[].response_status to see who's accepted
7. Busy/Free - Use transparency field: "opaque" = busy, "transparent" = free
8. Calendar Colors - Event doesn't include color, but you can use calendar color from List Calendars
9. Large Results - If you have many events, use smaller date ranges or lower max_results
10. Cancelled Events - By default excluded. Set include_cancelled=true to see them

Limitations

1. OAuth Only - Requires Google Account with OAuth (App Passwords don't support Calendar API)
2. No Pagination - Returns up to max_results events (max 2500). For more, use multiple queries with date ranges
3. Single Calendar - Searches one calendar at a time. For multiple calendars, call tool multiple times
4. Query Searches Summary & Description Only - Cannot search by location, attendee names, or other fields
5. Rate Limits - Google Calendar API has rate limits (typically 1,000,000 requests/day on free tier)

Related Tools

• List Calendars - Get calendar IDs to use with this tool
• Create Event - Create new calendar events
• Update Event (coming soon)
• Delete Event (coming soon)

Billing

Cost: 1 credit per execution

Fixed cost regardless of number of events returned or date range.