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

# Google Calendar

> Google Calendar Scenario seeding parameters, nested fields, and examples

Use `google_calendar` in `twins` and put this configuration under `seed_config.google_calendar`.

Google Calendar with calendars and events.

## Example seed

This is the complete Scenario request body for [creating a Scenario](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`.

```json theme={null}
{
  "name": "Google Calendar eval fixture",
  "twins": [
    "google_calendar"
  ],
  "seed_config": {
    "google_calendar": {
      "email": "viewer@example.com",
      "rooms": [
        {
          "name": "Atlas",
          "email": "atlas@rooms.example.com",
          "capacity": 6,
          "building": "Main",
          "timeZone": "America/Vancouver"
        }
      ],
      "task_lists": [
        {
          "id": "default",
          "title": "My Tasks",
          "sort": "myOrder",
          "tasks": [
            {
              "title": "Prepare meeting agenda",
              "notes": "Review the project brief",
              "starred": false,
              "status": "needsAction"
            }
          ]
        }
      ],
      "task_preferences": {
        "selectedListId": "default"
      },
      "calendars": [
        {
          "name": "Calendar Name",
          "owner_email": "owner@example.com",
          "acl": [
            {
              "scope": {
                "type": "user",
                "value": "viewer@example.com"
              },
              "role": "reader"
            }
          ],
          "subscribed": true,
          "timezone": "America/Vancouver",
          "events": [
            {
              "summary": "Event Title",
              "start": "2026-04-03T10:00:00Z",
              "end": "2026-04-03T11:00:00Z",
              "attendees": [
                {
                  "email": "alice@example.com"
                },
                {
                  "email": "bob@example.com"
                }
              ],
              "recurrence": [
                "RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
              ],
              "status": "confirmed",
              "conferenceData": {
                "createRequest": {
                  "requestId": "scenario-meet"
                }
              }
            },
            {
              "summary": "Undated Event With Timing Constraints",
              "all_day": false,
              "start_time": "10:00:00",
              "duration_minutes": 60,
              "timezone": "UTC"
            }
          ]
        }
      ]
    }
  }
}
```

## Parameters

### Top-level fields: `seed_config.google_calendar`

| Parameter | Type | Description |
| - | - | - |
| `email` | string | Main account email. |
| `base_time` | ISO-8601 datetime string | Reference clock. Omit to use the current clock. |
| `seed` | integer | Deterministic seed value. |
| `clock_step_seconds` | integer, 1-86400 | Logical clock increment. Default: `37`. |
| `calendars` | object\[] | Calendars with nested events and sharing grants. |
| `groups` | string\[] | Main account's group memberships, identified by group address. |
| `rooms` | object\[] | Room resources; maximum 200. |
| `task_lists` | object\[] or object map | Personal task lists with optional nested tasks. |
| `side_tasks` | object map keyed by task ID | Native personal-task fixtures. |
| `task_preferences` | object | Selected task-list preference. |

### Calendars: `google_calendar.calendars[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Explicit calendar ID. Otherwise generated. |
| `name` | string | Calendar name. Default: `Calendar`. |
| `timeZone` / `timezone` | IANA timezone string | Default: `UTC`. |
| `owner_email` | string | Owner address. Defaults to the main account. A separate owner account is created when needed. |
| `is_primary` | boolean | Defaults to `true` for the first seeded calendar belonging to each owner and `false` for subsequent calendars. |
| `events` | object\[] | Event fixtures. |
| `acl` | object\[] | Sharing grants. |
| `subscribed` | boolean | Subscribe the main account to a calendar owned by another account. Default: `false`. |
| `preferences` | object | Subscription preferences; applied when subscribing to another owner's calendar. |

### Events: `calendars[].events[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Explicit event ID. Otherwise generated. |
| `summary` | string | Event title. Default: `Event`. |
| `description` | string | Description. |
| `location` | string | Location. |
| `start` | string or time object | ISO datetime, `YYYY-MM-DD`, or Google-style time object. |
| `end` | string or time object | Same forms as `start`. All-day end dates are exclusive. |
| `timezone` | IANA timezone string | Event timezone. Falls back to the time object's `timeZone`, then the calendar's timezone. |
| `all_day` | boolean | Seed an all-day event. |
| `start_time` | time string | Local start time, e.g. `15:00:00`, when explicit dates/times are omitted. |
| `duration_minutes` | integer | Used to derive a missing boundary. Default: 60 minutes for timed events, one day for all-day events. |
| `organizer` | person object | Organizer identity. |
| `creator` | person object | Creator identity. |
| `attendees` | array of strings or objects | Email addresses or Google-style attendee objects. |
| `recurrence` | string or string\[] | Recurrence lines, e.g. `RRULE:FREQ=WEEKLY;COUNT=4`. |
| `status` | string | `confirmed`, `tentative`, or `cancelled`. |
| `transparency` | string | `opaque` or `transparent`. |
| `visibility` | string | `default`, `public`, `private`, or `confidential`. |
| `reminders` | object | Reminder configuration. |
| `attachments` | object\[] | Google-style event attachments. |
| `extendedProperties` | object | Private/shared string metadata. |
| `conferenceData` / `conference_data` | object or shorthand array | Conference information. |
| `sendUpdates` | string | `all`, `externalOnly`, or `none`; controls twin invitation/update behavior. |

These are the event fields explicitly forwarded by the Scenario seeder. Other fields supported by the Calendar API may require normal provider API calls after seeding or a complete exported snapshot.

Time behavior:

* A timed boundary can be a string such as `2026-11-06T14:00:00Z`, or `{"dateTime":"2026-11-06T14:00:00Z","timeZone":"UTC"}`.
* An all-day boundary can be `2026-11-06` or `{"date":"2026-11-06"}`.
* When one boundary is omitted, the seeder derives it using `duration_minutes`.
* When both are omitted, the event uses the reference clock's current date in the event/calendar timezone. `start_time` selects a time on that date; otherwise timed events start at the reference time.

### Nested event objects

`organizer` and `creator` accept `email`, `displayName` / `display_name` / `name`, and `self`.

Attendee objects are preserved as Google-style objects. Their standard fields include `id`, `email`, `displayName`, `organizer`, `self`, `resource`, `optional`, `responseStatus`, `comment`, `additionalGuests`, and `asyncOperation`. `responseStatus` uses `needsAction`, `accepted`, `declined`, or `tentative`.

| Object | Structure |
| - | - |
| `reminders` | `{"useDefault":false,"overrides":[{"method":"popup","minutes":10}]}` |
| `attachments[]` | Google attachment object with `fileUrl`, `title`, `mimeType`, `iconLink`, and/or `fileId`. |
| `extendedProperties` | `{"private":{"key":"value"},"shared":{"key":"value"}}` |
| `conferenceData` | Google conference object containing `entryPoints`; other conference metadata is preserved when entry points are supplied. |
| Conference shorthand entry | `{"type":"video","uri":"https://meet.example.test/meeting","label":"Meeting"}` |

Reminders allow at most five overrides. Each `method` is `email` or `popup`, and `minutes` is an integer from 0 to 40320. Set `useDefault` to `false` when supplying nonempty overrides.

Conference entry points accept Google fields such as `entryPointType`, `uri`, `label`, `pin`, `accessCode`, `meetingCode`, `passcode`, and `password`. Conference metadata can include `conferenceId`, `conferenceSolution`, `signature`, `notes`, and `createRequest`. A nonempty conference configuration without entry points generates a twin Meet link.

### Sharing grants: `calendars[].acl[]`

| Parameter | Type | Description |
| - | - | - |
| `scope` | object, **required** | Sharing recipient scope. |
| `scope.type` | string, **required** | `user`, `group`, `domain`, or `default`. |
| `scope.value` | string | Required for user, group, and domain scopes. Use an address for user/group and a domain for domain scope. |
| `role` | string | `none`, `freeBusyReader`, `reader`, `writerWithoutPrivateAccess`, `writer`, or `owner`. Default: `reader`. |

For a public `default` scope, the allowed roles are `none`, `freeBusyReader`, and `reader`.

### Subscription preferences: `calendars[].preferences`

| Parameter | Type | Description |
| - | - | - |
| `summaryOverride` | string | Display-name override. |
| `colorId` | string | Calendar color identifier. |
| `selected` | boolean | Selected in the calendar list. Default: `true`. |
| `hidden` | boolean | Hidden in the calendar list. Default: `false`. |
| `backgroundColor` | string | Hex color, e.g. `#5A8CAC`. |
| `foregroundColor` | string | Hex color. |
| `defaultReminders` | object\[] | Reminder entries containing `method` and `minutes`, with the same limits as event overrides. |
| `notificationSettings` | object | Contains `notifications: object[]`. |

Each `notificationSettings.notifications[]` entry accepts:

* `method`: `email`.
* `type`: `eventCreation`, `eventChange`, `eventCancellation`, `eventResponse`, or `agenda`.

### Rooms: `google_calendar.rooms[]`

| Parameter | Type | Description |
| - | - | - |
| `email` | string, **required** | Resource email address. |
| `name` | string | Room display name. Defaults to its address when omitted. |
| `capacity` | nonnegative integer | Capacity metadata. Default: `0`. |
| `timeZone` | IANA timezone string | Default: `UTC`. |
| `workspace_id` | string | Optional workspace filter. Normally omitted to use the current workspace. |

### Personal task lists: `google_calendar.task_lists`

Accepts an array of list objects or an object keyed by list ID. Each list accepts:

| Parameter | Type | Description |
| - | - | - |
| `id` | string | List ID. Generated when omitted from an array; inferred from the map key otherwise. |
| `kind` | string | Must be `tasks#taskList` when supplied. |
| `title` | string, **required** | Nonempty list name, maximum 1024 characters. |
| `sort` | string | `myOrder`, `date`, `starred`, or `title`. Default: `myOrder`. |
| `updated` | datetime string | ISO-8601 timestamp with timezone. |
| `tasks` | object\[] | Nested tasks belonging to this list. |

### Personal tasks: `task_lists[].tasks[]` or `google_calendar.side_tasks.<id>`

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Task ID. Generated for nested fixtures when omitted, or inferred from the native map key. |
| `kind` | string | Must be `tasks#task` when supplied. |
| `listId` | string | Containing list ID. Inferred for nested tasks; defaults to `default` for standalone tasks. |
| `title` | string, **required** | Nonempty task title, maximum 1024 characters. |
| `notes` | string | Task details, maximum 8192 characters. |
| `due` | string or null | `YYYY-MM-DD` or the same date in `YYYY-MM-DDT00:00:00Z` form. Empty/null clears the date. |
| `starred` | boolean | Default: `false`. |
| `starredAt` | datetime string | ISO-8601 timestamp with timezone; valid only for starred tasks. |
| `status` | string | `needsAction` or `completed`. Default: `needsAction`. |
| `deleted` | boolean | Deleted-task fixture flag. |
| `position` | string | Exactly 20 decimal digits. Generated when omitted. |
| `updated` | datetime string | ISO-8601 timestamp with timezone. Defaults to the reference time. |
| `completed` | datetime string | ISO-8601 timestamp with timezone; valid only for completed tasks. Defaults to the reference time for completed tasks. |

Task and list IDs contain 1-128 letters, digits, underscores, or hyphens. IDs must match native map keys when maps are used. Nested tasks must reference their containing list; active standalone tasks must reference an existing list.

### Task preferences: `google_calendar.task_preferences`

| Parameter | Type | Description |
| - | - | - |
| `selectedListId` | string, **required** | Existing list ID. When `task_preferences` is omitted, the selection defaults to `default`. |

These are personal Calendar side-panel task fixtures.

## Snapshot restore

You can alternatively supply `native_snapshot` containing a complete exported native state. Reuse the export intact. A legacy `runtime_snapshot` restore path is also retained.

## API coverage and limitations

**Twin name:** `google_calendar`

**CLI quickstart:** [Use the Google Workspace CLI with Arga twins](https://docs.argalabs.com/features/google-workspace-cli)

**Supports**

* Google Calendar API v3 calendars, calendar list, events, ACL rules, settings, colors, and free/busy queries.
* Watch channels and webhook delivery for events, ACL, calendar list, and settings resources.
* Calendar CRUD, event import, quick-add, instances, move operations, and delete flows.

**Known limitations**

* Calendar and event state starts empty unless seeded or created by the app under test.
* Advanced Google Calendar edge cases outside the modeled v3 resources may be approximated or return structured errors.
* Watch delivery is deterministic and inspectable, which is useful for tests but not identical to every production timing detail.

**MCP tools:** `get_twin_catalog`, `provision_twins`, `start_url_validation`, `get_validation_results`.

> [!NOTE]
>
> Google Drive, Docs, and Sheets remain separate provisioning and API surfaces. When you provision any two or more under the same Twin Run ID, the selected twins share one run-scoped Google file state. Metadata, content, permissions, revisions, creates, edits, renames, trash, and deletes stay synchronized. Different Twin Run IDs never share this state.

See [Scenario seeding](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures.


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