Get This Week's Events

Get all events for the current week, organized by day. See your entire week's schedule at a glance.

Overview

The Get This Week's Events tool retrieves all events for the current week and organizes them by day. It:

• Groups events by day of the week (Monday through Sunday, or Sunday through Saturday)
• Calculates the current week based on your calendar's timezone
• Provides summary statistics including busiest day
• Supports both Monday-start and Sunday-start weeks

Prerequisites

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

Usage

Basic Usage (Monday Start)

Get this week's events with default Monday start:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {}
}

Sunday Start Week

Get this week's events with Sunday as first day:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {
    "start_of_week": "sunday"
  }
}

Specific Calendar

Get this week's events from a work calendar:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {
    "calendar_id": "work@company.com",
    "start_of_week": "monday"
  }
}

Custom Timezone

View the week in a different timezone:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {
    "timezone": "Europe/London",
    "start_of_week": "monday"
  }
}

Useful when traveling to see your week in the destination timezone.

Input Parameters

Parameter	Type	Required	Default	Description
start_of_week	string	No	"monday"	Which day the week starts on. Must be "monday" or "sunday".
calendar_id	string	No	"primary"	Calendar identifier. Use "primary" for main calendar.
timezone	string	No	calendar tz	IANA timezone. Determines week boundaries.

Start of Week

• "monday" - ISO standard (Monday through Sunday)
• "sunday" - US convention (Sunday through Saturday)

Response Format

Success Response with Events

{
  "success": true,
  "week_start": "2024-01-15",
  "week_end": "2024-01-21",
  "start_of_week": "monday",
  "events_by_day": {
    "monday": {
      "date": "2024-01-15",
      "events": [
        {
          "id": "abc123",
          "summary": "Morning Standup",
          "start": "2024-01-15T09:00:00-08:00",
          "end": "2024-01-15T09:30:00-08:00",
          "location": "",
          "all_day": false,
          "attendees_count": 5
        },
        {
          "id": "def456",
          "summary": "Project Review",
          "start": "2024-01-15T14:00:00-08:00",
          "end": "2024-01-15T15:30:00-08:00",
          "location": "Conference Room",
          "all_day": false,
          "attendees_count": 3
        }
      ],
      "event_count": 2
    },
    "tuesday": {
      "date": "2024-01-16",
      "events": [],
      "event_count": 0
    },
    "wednesday": {
      "date": "2024-01-17",
      "events": [
        {
          "id": "xyz789",
          "summary": "Client Call",
          "start": "2024-01-17T11:00:00-08:00",
          "end": "2024-01-17T12:00:00-08:00",
          "all_day": false,
          "attendees_count": 2
        }
      ],
      "event_count": 1
    },
    "thursday": {
      "date": "2024-01-18",
      "events": [],
      "event_count": 0
    },
    "friday": {
      "date": "2024-01-19",
      "events": [],
      "event_count": 0
    },
    "saturday": {
      "date": "2024-01-20",
      "events": [],
      "event_count": 0
    },
    "sunday": {
      "date": "2024-01-21",
      "events": [],
      "event_count": 0
    }
  },
  "total_events": 3,
  "calendar_id": "primary",
  "timezone": "America/Los_Angeles",
  "summary": {
    "total": 3,
    "all_day_events": 0,
    "timed_events": 3,
    "days_with_events": 2,
    "busiest_day": {
      "day": "monday",
      "date": "2024-01-15",
      "event_count": 2
    }
  }
}

Success Response with No Events

{
  "success": true,
  "week_start": "2024-01-15",
  "week_end": "2024-01-21",
  "start_of_week": "monday",
  "events_by_day": {
    "monday": {"date": "2024-01-15", "events": [], "event_count": 0},
    "tuesday": {"date": "2024-01-16", "events": [], "event_count": 0},
    "wednesday": {"date": "2024-01-17", "events": [], "event_count": 0},
    "thursday": {"date": "2024-01-18", "events": [], "event_count": 0},
    "friday": {"date": "2024-01-19", "events": [], "event_count": 0},
    "saturday": {"date": "2024-01-20", "events": [], "event_count": 0},
    "sunday": {"date": "2024-01-21", "events": [], "event_count": 0}
  },
  "total_events": 0,
  "calendar_id": "primary",
  "timezone": "America/Los_Angeles",
  "summary": {
    "total": 0,
    "all_day_events": 0,
    "timed_events": 0,
    "days_with_events": 0,
    "busiest_day": null
  }
}

Response Fields

Field	Type	Description
week_start	string	First day of week (YYYY-MM-DD)
week_end	string	Last day of week (YYYY-MM-DD)
start_of_week	string	Week start setting used ("monday" or "sunday")
events_by_day	object	Events grouped by day (see below)
total_events	integer	Total events across all days
calendar_id	string	Which calendar was queried
timezone	string	Timezone used for week calculation
Summary
summary.total	integer	Total events
summary.all_day_events	integer	Count of all-day events
summary.timed_events	integer	Count of timed events
summary.days_with_events	integer	Number of days that have at least one event
summary.busiest_day	object	Day with most events (null if no events)

Events By Day Structure

Each day (monday, tuesday, etc.) contains:

• date: Date in YYYY-MM-DD format
• events: Array of event objects (same format as Get Events)
• event_count: Number of events on this day

Use Cases

1. Weekly Planning

Review your week on Sunday evening or Monday morning:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {
    "start_of_week": "monday"
  }
}

2. Find Light Days

Identify days with fewer meetings:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {}
}

Look at event_count for each day. Days with 0 or few events are good for deep work.

3. Balance Check

See if your week is balanced:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {
    "calendar_id": "primary"
  }
}

Check summary.busiest_day to see if one day is overloaded.

4. Team Calendar View

See team events for the week:

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

5. Multi-Timezone Planning

Traveling this week? See events in destination timezone:

{
  "tool": "google_calendar_Get_Weeks_Events",
  "arguments": {
    "timezone": "Asia/Tokyo"
  }
}

Error Handling

Invalid Start of Week

Error:

{
  "error": "Invalid start_of_week 'tuesday'. Must be 'monday' or 'sunday'."
}

Solution: Use either "monday" or "sunday".

Invalid Timezone

Error:

{
  "error": "Invalid timezone 'PST'. Use IANA timezone format (e.g., 'America/Los_Angeles')"
}

Solution: Use valid IANA timezone names like "America/Los_Angeles", not abbreviations like "PST".

Calendar Not Found

Error:

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

Solution: Use List Calendars to find valid calendar IDs.

Tips

1. Week Boundaries - The week is calculated from the current date. If today is Wednesday, Monday-start gives you Monday-Sunday of the current week.

2. Multi-Day Events - Events that span multiple days appear only on their start day in the grouping.

3. Empty Days - Days with no events are included with empty arrays. This makes it easy to identify free days.

4. Busiest Day - Use summary.busiest_day to quickly identify your most packed day and consider rescheduling if needed.

5. Day Names - Always lowercase in response: "monday", "tuesday", etc.

6. Recurring Events - Each occurrence is shown as a separate event (already expanded).

7. Default Monday - Matches ISO 8601 standard. Most businesses and project management tools use Monday start.

8. Sunday Start - Common in US calendars and useful for planning weekends as part of the week.

9. Combine with Find Slot - Use this to see your week, then use Find Next Available Slot to schedule on light days.

10. Weekly Review - Great for end-of-week review or start-of-week planning workflows.

Limitations

1. Current Week Only - Cannot specify a different week. Use Get Events for custom date ranges.

2. Single Calendar - Checks one calendar at a time. Call multiple times for multiple calendars.

3. OAuth Only - Requires Google Account with OAuth (App Passwords don't support Calendar API).

4. No Filtering - Returns all events for the week. Filter results in your application if needed.

5. Multi-Day Events - Show on start day only. The event object still contains full date range in its fields.

Related Tools

• Get Today's Events - See just today's schedule
• Get Events - Custom date ranges and search
• Find Next Available Slot - Find free time in your week
• Check Availability - Check specific time slots
• List Calendars - Get calendar IDs

Billing

Cost: 1 credit per execution

Fixed cost regardless of how many events are returned.