> ## 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 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.
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 |
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.
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.
**Code slugs** — integration slug: `googleCalendar` · actions: `listEvents`,
`getEvent`, `listUsers`. In a [workflow](/workflows/overview), declare the
connector in `uses` and call `uses..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.
**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.