> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits, valid for its first 30 days, and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Google Calendar

> Read Google Calendar events for one user, or for every user of a Google Workspace domain through domain-wide delegation.

Google Calendar in Cargo is **read-only**. A connector can list and read events and see who was invited, and it can never create, change or delete anything on a calendar. What it can read depends entirely on which of the two authentication methods you pick.

## How to set up Google Calendar

| | Reads | Set up by |
| - | - | - |
| **OAuth 2** | The calendars of the person who connects | Anyone, in a browser |
| **Domain-wide delegation** | Every user's calendar in a Google Workspace domain | A Workspace super admin, once |

Pick OAuth to read one rep's calendar, or your own. Pick delegation when a workflow has to look across the whole team — every meeting booked in the company this week, who an account met with, which reps have free time.

### OAuth

1. In Cargo, go to **Settings** → **Integrations** → **Add connection** and choose **Google Calendar**
2. Under **Authentication**, select **OAuth 2**
3. Click to connect, sign in with the Google account whose calendars you want to read, and grant access

Cargo asks for one scope, `calendar.readonly`, and stores the connected address on the connector so actions know whose calendar they are reading. The **User** field on the event actions is ignored for an OAuth connector — there is only one calendar owner.

> [!NOTE]
>
> An OAuth connector sees what that one Google account sees: their own
> calendars, plus any calendar shared with them. To read a colleague's calendar
> this way, they have to share it with the connected account first.

### Domain-wide delegation

Delegation reads the whole domain without asking each person to connect. It works like this:

* Cargo owns a **service account** — a robot identity in Cargo's own Google Cloud project. On its own it has access to nothing of yours.
* Your Workspace super admin **authorizes that service account once**, in the Admin console, for two read-only scopes. This is the grant, and it says: this client may act as any user in my domain, limited to these scopes.
* From then on Cargo **acts as each user** when it reads their calendar. Nobody is prompted, no user has to connect, and no key ever leaves your Workspace.

#### Set it up

In Cargo, go to **Settings** → **Integrations** → **Add connection**, choose **Google Calendar**, and select **Domain-wide delegation**. The form then shows the two values your admin needs — **Client ID** and **OAuth scopes** — so you can copy them straight out of it. Fill in:

| Field | Value |
| - | - |
| **Workspace domain** | The domain whose users you want to read, for example `acme.com` |
| **Super admin sign-in** | A super admin of that domain signs in with Google. Cargo acts as this admin to list the domain's users |

> [!NOTE]
>
> Only a super admin of the domain can connect it. Cargo's client id is the same
> for every customer, so the sign-in is what proves the domain is yours: Cargo
> asks Google who signed in and connects only when the account is at that domain
> and is a super admin there. Nobody else can connect your domain, even after
> you authorize Cargo's client id.

Before signing in, the super admin authorizes Cargo, once:

1. Open [Domain-wide delegation](https://admin.google.com/ac/owl/domainwidedelegation) in the Google Admin console — **Security** → **Access and data control** → **API controls** → **Manage domain-wide delegation**
2. Click **Add new**
3. Paste the **Client ID** shown in the Cargo form. It is Cargo's service account, the same for every customer
4. Paste the **OAuth scopes**, comma separated, also shown in the Cargo form:

```
https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly
```

5. Click **Authorize**

The second scope is what lets Cargo list the domain's users, so that actions and pickers can offer them. Both are `readonly`: the grant carries no ability to write to a calendar or to change anything about a user.

Then sign in and save the connector. Cargo verifies the grant by reading one directory user as the admin who signed in, so a connector saved before the authorization fails with a message naming the domain — authorize it, then connect again.

Connect delegation from the Cargo app rather than in code: it needs a super admin to sign in with Google, which a connector declared in code cannot do.

> [!WARNING]
>
> Delegation is broad by design. Acting as a user means seeing what that user
> sees, including the titles, descriptions and guest lists of meetings they
> consider private. Grant it deliberately, and expect to explain the scope to
> whoever owns security at your company. The same Admin console screen revokes
> it in one click, which cuts off every access immediately.

> [!NOTE]
>
> **Code slugs** — integration slug: `googleCalendar` · actions: `listEvents`,
> `getEvent`, `listUsers`. In a [workflow](https://docs.getcargo.ai/workflows/overview.md), declare the
> connector in `uses` and call `uses.<key>.listEvents(...)`.

## Google Calendar actions

Both event actions take a **User** and a **Calendar** field backed by a picker: the user list comes from your Workspace directory, and the calendar list from that user's own calendars. **Calendar** defaults to `primary`, the user's main calendar.

> [!NOTE]
>
> **User** is required on a delegation connector — it is the person Cargo acts
> as, and there is no "every calendar at once" call. It has to be an address at
> the connector's own domain; anything else is refused. Leave it empty on an
> OAuth connector; it is ignored there. To sweep a whole domain, run **List
> users** first and iterate.

### List events

Lists the events on one calendar, earliest first. Recurring events are expanded, so a weekly stand-up comes back as one entry per occurrence in the window rather than a single rule.

**Configuration:**

* **User**: whose calendar to read
* **Calendar** (optional): defaults to `primary`
* **From** (optional): only events ending after this time, as an RFC 3339 timestamp (`2026-10-05T00:00:00Z`)
* **To** (optional): only events starting before this time
* **Search** (optional): free text matched against title, description, location and attendees
* **Max results** (optional): defaults to 50, up to 250

Always set **From**. Results are ordered earliest first, so leaving it empty hands back the *oldest* events on the calendar rather than the upcoming ones — set `now` for "what's next", or the start of the week for a look back.

### Get event

Reads one event by id, returning the same shape as **List events**.

**Configuration:**

* **User**: whose calendar the event is on
* **Calendar** (optional): defaults to `primary`
* **Event ID**: the event's id, as returned by **List events**

### List users

Lists the people whose calendars this connector can read: every active user in the Workspace under delegation, or just the connected user under OAuth. Suspended and archived accounts are left out.

**Configuration:**

* **Search** (optional): a Directory query narrowing the result — `name:Dana`, `email:dana*`. Domain-wide delegation only

Returns `email` and `name`. Use it as the first step of any workflow that walks a whole team's calendars.

## Event shape

Both event actions return the same flattened record, so you can map fields without running the node first:

| Field | Meaning |
| - | - |
| `id` | The event's id, for **Get event** |
| `status` | `confirmed`, `tentative` or `cancelled` |
| `title`, `description`, `location` | As shown on the event |
| `start`, `end` | RFC 3339 timestamps for a timed event; plain `YYYY-MM-DD` dates for an all-day one. An all-day `end` is the last day of the event |
| `isAllDay` | Which of the two the dates above are |
| `timeZone` | The event's time zone |
| `organizerEmail` | Who owns the event |
| `attendees` | `email`, `name`, `responseStatus`, `isOrganizer`, `isOptional` per guest |
| `conferenceUrl` | The Meet link, or another video entry point when there is no Meet |
| `url` | The event in Google Calendar |
| `recurringEventId` | Set when this is one occurrence of a repeating event |
| `createdAt`, `updatedAt` | When the event was created and last changed |

`responseStatus` is Google's own: `accepted`, `declined`, `tentative` or `needsAction`. Treat `needsAction` as "no answer yet", not as a decline.

## Rate limits

Cargo spreads calls at 300 requests per minute across the connector. Each event read is one request, so a sweep over a large domain works through the users at that pace — **List users** on a 500-person Workspace followed by **List events** per user is 500-odd requests, a couple of minutes of wall clock.

Narrow the window with **From** and **To** rather than pulling a year of history and filtering afterwards.

## Security

* Both methods use read-only scopes. There is no path through this integration that writes to a calendar
* OAuth tokens are encrypted at rest and revocable from the connected Google account at any time
* A delegation grant is revoked from the same Admin console screen that created it, which cuts off access immediately and for every user at once
* Cargo's service-account key lives only in Cargo's infrastructure. Nothing about delegation asks you to generate, upload or hold a key
* A delegation connector is pinned to one domain, on both sides. Only a Cargo workspace that belongs to the domain can connect it, and the connector can only ever act as a user of that domain — so authorizing Cargo's client id exposes your calendars to your own workspace and to nobody else's


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.