Advanced Analytica Advanced Analytica: IBOM
← All connectors
Google Calendar logo

Source connector

Google Calendar

Set up Google Calendar as a source and move its data into your chosen destination.

Version 1.2.0 community alpha

Google Calendar

Use this page to set up the Google Calendar source connector and find reference information.

Prerequisites

  • A Google account with access to the calendars you want to sync.
  • Airbyte Cloud: sign in with Google during setup through Airbyte’s OAuth app. Alternatively, use your own OAuth app as described below.
  • Airbyte Open Source: a Google Cloud project with the Google Calendar API enabled. You’ll also need OAuth credentials: Client ID, Client Secret, and a Refresh Token. Follow the setup steps below.
  • (Optional) A specific Calendar ID to sync only events, acl, and freebusy from one calendar.
  • (Optional) A Start Date to limit event modification times. This applies to Full Refresh, initial Incremental syncs, and full re-reads.

Setup guide

Set up your Google Calendar credentials, then configure the source in Airbyte.

Set up Google Calendar

On Airbyte Cloud, choose Authenticate via Google (OAuth) in the Airbyte setup to sign in through Airbyte’s OAuth app. You don’t need to create your own project. This flow requests six scopes: calendar.calendarlist.readonly, calendar.calendars.readonly, calendar.events.readonly, calendar.settings.readonly, calendar.freebusy, and calendar.acls.readonly. Each scope starts with https://www.googleapis.com/auth/. Google lists each permission separately on its consent screen. Allow every permission. If you leave a permission unchecked, its stream fails with a missing-scope error. Re-authenticate and allow the permission to resolve it.

For Airbyte Open Source, or to use Authenticate with custom app (client ID / secret) on Cloud, get three credentials from your Google Cloud project: Client ID, Client secret, and Refresh token.

  1. Enable the Google Calendar API for your project in the API Library.
  2. Configure the OAuth consent screen. Google won’t create an OAuth client until the project has one. For a Google Workspace account in a Google Cloud organization, choose Internal. Otherwise, choose External and set the publishing status to In production. Google expires refresh tokens for an External app in Testing after 7 days. Syncs then fail with an authentication error. The Calendar scopes are sensitive. In production, an unverified app displays a “Google hasn’t verified this app” warning during authorisation. You can continue past the warning for your own account. Add the calendar.readonly and calendar.acls.readonly scopes.
  3. Create an OAuth client with type Web application on the Credentials page. Add https://developers.google.com/oauthplayground as an authorised redirect URI.
  4. Get a refresh token with the OAuth 2.0 Playground:
    • Click the gear icon and check Use your own OAuth credentials. Then enter your Client ID and Client Secret.
    • Authorise the https://www.googleapis.com/auth/calendar.readonly and https://www.googleapis.com/auth/calendar.acls.readonly scopes. Then exchange the authorisation code for tokens. The calendar.acls.readonly scope is required for the acl stream. calendar.readonly alone supports every other stream. Instead of calendar.readonly, you can authorise the five granular scopes requested by Airbyte Cloud’s OAuth flow. These are calendar.calendarlist.readonly, calendar.calendars.readonly, calendar.events.readonly, calendar.settings.readonly, and calendar.freebusy.

Set up the connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Google Calendar from the Source type dropdown.
  4. Enter a name for the connector.
  5. Under Authentication, choose Authenticate via Google (OAuth) and authorise your Google account. Alternatively, choose Authenticate with custom app (client ID / secret). Enter your app’s Client ID, Client secret, and Refresh token from Google Calendar setup.
  6. (Optional) For Calendar Id, enter a calendar ID. This syncs only events, acl, and freebusy from that calendar. calendarlist and calendars ignore this setting. The calendar doesn’t need to appear in the account’s calendar list. The connector reads it directly. Use primary for the account’s primary calendar. Leave this empty to sync every listed calendar, including hidden calendars.
  7. (Optional) For Start Date, enter the earliest event updated timestamp. Use the format YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.SSSZ. When unset, the cursor starts at 2000-01-01T00:00:00Z. During an initial sync or full re-read, the connector applies the filter server-side only for dates within the last 21 days. For earlier dates, it reads the calendar and drops older events itself. See Events sync behavior.
  8. (Optional) For Number of concurrent workers, set 1–10 concurrent request workers. The default is 3. Values below 2 run with 2 workers.
  9. Click Set up source and wait for the tests to finish.

For Airbyte Open Source:

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Google Calendar from the Source type dropdown.
  4. Enter a name for the connector.
  5. Under Authentication, choose Authenticate with custom app (client ID / secret). Enter the Client ID, Client secret, and Refresh token from Google Calendar setup. The refresh token must come from your own Google Cloud OAuth app. It must include the calendar.readonly and calendar.acls.readonly scopes. Also provide that app’s client ID and client secret. Without calendar.acls.readonly, the acl stream fails with a configuration error. Generate a refresh token containing the scope, or deselect the stream.
  6. (Optional) For Calendar Id, enter a calendar ID. This syncs only events, acl, and freebusy from that calendar. Use primary for the account’s primary calendar. calendarlist and calendars ignore this setting. The calendar doesn’t need to appear in the account’s calendar list. The connector reads it directly. Leave this empty to sync every listed calendar, including hidden calendars.
  7. (Optional) For Start Date, enter the earliest event updated timestamp. Use YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss.SSSZ. When unset, the cursor starts at 2000-01-01T00:00:00Z. During an initial sync or full re-read, the connector applies the filter server-side only for dates within the last 21 days. For earlier dates, it reads the calendar and drops older events itself. See Events sync behavior.
  8. (Optional) For Number of concurrent workers, set 1–10 concurrent request workers. The default is 3. Values below 2 run with 2 workers.
  9. Click Set up source and wait for the tests to finish.

Configuration files and saved connections

When using a configuration file, the Airbyte API, or Terraform, you must provide credentials. It contains these fields:

  • auth_type: use oauth2.0 for Authenticate via Google (OAuth) or manual for Authenticate with custom app (client ID / secret).
  • client_id, client_secret, and refresh_token. The OAuth flow completes these fields for the oauth2.0 option.

The optional top-level fields are calendarid, start_date, and num_workers. The default is 3, and the range is 1–10. Values below 2 run with 2 workers.

Before version 1.1.0, credentials used the top-level fields client_id, client_secret, and client_refresh_token_2. On its first run with version 1.1.0 or later, the connector rewrites saved configurations using these fields. It moves them to credentials with auth_type: manual. Existing connections continue using the same OAuth app. Keep these points in mind:

  • The Airbyte API and Terraform validate new and updated configurations against the 1.1.0 spec before running the connector. They must therefore use the credentials fields. This requirement includes the next apply of an existing Terraform resource.
  • After that first run, downgrading a connection below 1.1.0 requires you to restore the top-level fields manually.

Supported sync modes

The Google Calendar source connector supports these sync modes:

Supported streams

The events, acl, and freebusy streams sync once for each calendar. When you configure Calendar Id, only that calendar syncs. The connector reads it directly, so it doesn’t need to appear in the account’s calendar list. Otherwise, every calendar in the account’s calendar list syncs.

Stream NamePrimary KeyPaginationSupports Full SyncSupports Incremental
colorskindNo pagination✅❌
settingsidDefaultPaginator✅❌
calendarlistidDefaultPaginator✅❌
calendarsidNo pagination✅❌
eventscalendar_id, idDefaultPaginator✅✅
aclcalendar_id, idDefaultPaginator✅❌
freebusycalendar_id, start, endNo pagination✅❌

When Calendar Id is empty, events reads only calendars where the account can read events. acl reads only calendars it owns. freebusy reads every listed calendar.

Deleted events are replicated. Cancelled events arrive with status: "cancelled" (showDeleted=true) and receive an updated value. This means they replace the live row under Append + Deduped. See Events sync behavior.

Deleted calendar-list entries appear in calendarlist with deleted: true. Deleted sharing rules appear in acl with role: "none". Internal calendar-list reads don’t request deleted entries and prevent their use as child partitions. calendars, events, acl, and freebusy don’t read removed calendars. This prevents requests for calendars you can no longer access. The full-refresh calendars stream has no deletion record. A removed calendar disappears from the next snapshot, and its deletion appears in calendarlist.

Google user data

Airbyte follows the Google API Services User Data Policy, including Limited Use requirements, when transferring Google API information to another app.

Raw or derived data from Google Workspace APIs follows the Google User Data Policy, including Limited Use requirements. This includes data from the Google Calendar API. Airbyte doesn’t use this data to develop, improve or train generalised or non-personalised AI or machine learning models.

The connector only reads Calendar data to sync it to the destination configured in your connection.

IP allow list

If your organisation restricts specific IPs, add the Airbyte Cloud IP addresses to your allow list when using Airbyte Cloud.

Limitations and troubleshooting

Expand to see details about Google Calendar connector limitations and troubleshooting.

Connector limitations

  • API quota: The connector uses a moving-window budget of 500 requests/minute, including POST requests. It retries rateLimitExceeded / userRateLimitExceeded responses and HTTP 429 with exponential backoff. Other quotaExceeded / dailyLimitExceeded errors fail the sync as transient errors until the quota resets. These errors don’t require a configuration change. Project quotas can vary. See Google’s quota documentation.
  • Stale cursor: Google rejects an updatedMin that’s too far in the past. Testing measured this limit at 29 days, but Google doesn’t document it. If the saved cursor is older than 21 days, the connector clears it and re-reads every event. When set, Start Date limits this re-read. If Google still returns 410 updatedMinTooLongAgo, the connector treats it as a transient error. It automatically re-reads once the saved cursor is more than 21 days old. You can clear the events stream to re-read sooner. A 410 for a deleted calendar or fullSyncRequired is a configuration error.
  • calendars returns calendar resources, not list entries: The connector returns each listed calendar the account can read (minAccessRole=reader), including hidden calendars. Fields include kind, etag, id, summary, description, location, timeZone, conferenceProperties, dataOwner, autoAcceptInvitations and labelProperties. The per-user list fields remain in calendarlist. These fields are accessRole, colours, reminders, primary and selected. This stream reads the calendar list regardless of Calendar Id.
  • acl scope and ownership: The acl stream lists a calendar’s sharing rules. It requires the calendar.acls.readonly OAuth scope, or calendar.acls / calendar. Without this scope, the stream fails with a configuration error. Re-authenticate and allow every requested permission, or generate a new refresh token for your OAuth client. Include the scope and paste the token into Refresh token. Alternatively, deselect the stream. If your connection adds new streams automatically, deselect acl until the token includes the scope. Google only shows sharing rules to a calendar’s owner. The connector therefore skips calendars the account doesn’t own.
  • freebusy is a point-in-time window: The connector lists busy blocks from 30 days ago to 45 days ahead. It recalculates them during every sync, and start_date doesn’t apply. If Google can’t calculate free/busy for a calendar, the connector logs it and returns no rows. The destination therefore shows the same result as a free calendar. This data is a snapshot, not a historical record.
  • settings.value is always a string, including numeric-looking settings.
  • colors is a singleton: The connector returns one record containing calendar and event colour-palette objects.
  • Push notification channels (channels) aren’t synced by design. They’re write-only subscriptions that the connector would need to create, not readable data.

Troubleshooting

  • Syncs may start failing with a rejected refresh token (invalid_grant) about one week after setup. This probably means the OAuth app’s consent screen is an External app in Testing. Its refresh tokens expire after 7 days. Set its publishing status to In production and generate a new refresh token. Then paste it into Refresh token.
  • A missing OAuth scope error means a permission was unchecked on Google’s consent screen. Alternatively, the refresh token may omit a scope listed in Google Calendar setup. Re-authenticate and allow every requested permission, generate a new refresh token with the required scopes, or deselect the stream.
  • Find common Google Calendar source connector issues on the Airbyte Forum.

Events sync behaviour

The events stream syncs incrementally using the event’s last modification time (updated) and Google Calendar’s updatedMin filter.

  • Cancelled events are included (showDeleted=true) with status: cancelled, so deletions reach the destination. Google returns these as stubs without a modification time. The connector therefore sets their updated. It uses the saved cursor or one hour before the sync, whichever is later. Under Append + Deduped, this lets the cancelled row replace the live row. Filter status != 'cancelled' downstream if you only want live events.
  • calendar_id contains the calendar’s actual ID, so it joins to calendarlist.id / calendars.id. The connector resolves the primary alias to the account’s email address.
  • One cursor for all calendars. The stream uses one updated cursor across all calendars. A calendar added after the first sync starts from this cursor, so its older events aren’t synced. Clear the events stream to backfill them.
  • Recurring series are returned as one record (singleEvents=false). Individual occurrences aren’t expanded. The record’s updated shows when the series was last edited.
  • start_date limits events to those last modified on or after that date. This applies to every Full Refresh sync, the first Incremental sync and any full re-read. Full re-reads happen after a reset or when the saved cursor is older than 21 days. For these reads, the connector only sends updatedMin when the configured date falls within the previous 21 days. Otherwise, it downloads the calendar and removes older records itself. A recurring series counts as one event. A start date therefore removes series unchanged since that date, even when they still have upcoming occurrences. When unset, the cursor starts at 2000-01-01T00:00:00Z.
  • 29-day window. Google rejects updatedMin older than 29 days. This measured limit isn’t documented and has previously been shorter. The connector uses the newest updated it has seen as its cursor. If that cursor is older than 21 days when a sync starts, the connector clears it. This can happen when a calendar has no edits for three weeks or a connection is paused for three weeks. The connector then re-reads the full calendar, or everything since start_date, before continuing incrementally. A calendar with only deletions still advances its cursor, as explained under cancelled events. A calendar with no changes re-reads during every sync until something changes.
  • Recommended sync mode: Incremental | Append + Deduped uses calendar_id and id as the primary key. The same event id appears on every calendar containing that meeting. With plain Append, each re-read described above adds another copy of every event.

Changelog

Expand to review
VersionDatePull RequestSubject
1.2.02026-11-1192016Include calendar and ACL tombstones, expand schemas, and improve pagination and concurrency reliability.
1.1.02026-11-1186469Add declarative Google OAuth with granular read-only scopes and a custom-app authentication option; automatically migrate saved flat credentials (downgrading below 1.1.0 then needs them restored by hand); report a missing OAuth scope as a configuration error.
1.0.12026-11-1091570Update dependencies
1.0.02026-11-0986470Add acl and freebusy streams, read events/acl/freebusy from every calendar when calendarid is empty, change the events primary key to [calendar_id, id], return calendar resources from calendars, change the colors primary key to kind, and type date and date-time fields (breaking, see the migration guide)
0.1.42026-11-0390589Update dependencies
0.1.32026-10-2789924Update dependencies
0.1.22026-10-2089285Update dependencies
0.1.12026-10-1388641Update dependencies
0.1.02026-10-0786468Add error handling, API budget, concurrency, incremental events (now includes cancelled events via showDeleted=true) with a calendar_id column and an optional start_date, and enable acceptance tests
0.0.552026-10-0687901Update dependencies
0.0.542026-09-2987194Update dependencies
0.0.532026-09-2286679Update dependencies
0.0.522026-09-1586070Update dependencies
0.0.512026-09-0885541Update dependencies
0.0.502026-08-1884636Update dependencies
0.0.492026-08-1183962Update dependencies
0.0.482026-08-0483499Update dependencies
0.0.472026-07-2882972Update dependencies
0.0.462026-07-2182435Update dependencies
0.0.452026-07-1481849Update dependencies
0.0.442026-06-3081038Update dependencies
0.0.432026-06-2380483Update dependencies
0.0.422026-06-1679880Update dependencies
0.0.412026-06-0979339Update dependencies
0.0.402026-06-0278738Update dependencies
0.0.392026-04-2877268Update dependencies
0.0.382026-04-2176584Update dependencies
0.0.372026-03-3175671Update dependencies
0.0.362026-03-1774985Update dependencies
0.0.352026-02-2473746Update dependencies
0.0.342026-02-1773085Update dependencies
0.0.332026-01-2071931Update dependencies
0.0.322026-01-1471428Update dependencies
0.0.312025-12-1870696Update dependencies
0.0.302025-11-2569889Update dependencies
0.0.292025-11-1869373Update dependencies
0.0.282025-10-2969049Update dependencies
0.0.272025-10-2168310Update dependencies
0.0.262025-10-1468007Update dependencies
0.0.252025-10-0767257Update dependencies
0.0.242025-09-3066309Update dependencies
0.0.232025-09-0966046Update dependencies
0.0.222025-08-2365366Update dependencies
0.0.212025-08-0964614Update dependencies
0.0.202025-08-0264218Update dependencies
0.0.192025-07-2663813Update dependencies
0.0.182025-07-1963491Update dependencies
0.0.172025-07-1263149Update dependencies
0.0.162025-07-0562653Update dependencies
0.0.152025-06-2862156Update dependencies
0.0.142025-06-2161833Update dependencies
0.0.132025-06-1461121Update dependencies
0.0.122025-05-2460587Update dependencies
0.0.112025-05-1059250Update dependencies
0.0.102025-04-2658812Update dependencies
0.0.92025-04-1958175Update dependencies
0.0.82025-04-1257066Update dependencies
0.0.72025-03-2956487Update dependencies
0.0.62025-03-2255939Update dependencies
0.0.52025-03-0855325Update dependencies
0.0.42025-03-0154992Update dependencies
0.0.32025-02-2254395Update dependencies
0.0.22025-02-1547915Update dependencies
0.0.12024-10-06Initial release by @bala-ceg via Connector Builder
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.