# google-calendar.freebusy.query

Busy times of calendars between two times

> Returns free/busy information for a set of calendars.

Page: https://telipot.com/catalog/tasks/google-calendar.freebusy.query · Markdown: https://telipot.com/catalog/tasks/google-calendar.freebusy.query/md · JSON: https://telipot.com/catalog/tasks/google-calendar.freebusy.query/json

| Field | Value |
| --- | --- |
| provider | [Google Calendar](https://telipot.com/catalog/providers/google-calendar) `google-calendar` |
| capability | [`calendar.freebusy.query`](https://telipot.com/catalog/capabilities/calendar.freebusy.query) |
| kind | data |
| tier | core |
| price | Free (Free from the tool) |
| identity | Person’s own |
| auth | `oauth · OAuth 2.0 with PKCE` |
| scope | own_account |
| principal | user |
| required_scopes | `calendar.readonly` |
| retention | standard |
| route | `POST https://www.googleapis.com/calendar/v3/freeBusy` |
| verification | Not verified yet. Not checked yet. We test with a real request before we mark it. |
| status | live |
| docs | https://developers.google.com/workspace/calendar/api/v3/reference/freebusy/query |

## Preview the price · nothing runs

```bash
telipot run google-calendar.freebusy.query \
  --input-json '{"timeMin":"2026-10-12T00:00:00Z","timeMax":"2026-10-19T00:00:00Z","items":[{"id":"primary"}]}' \
  --as user:ana \
  --quote
```

## Run it

```bash
telipot run google-calendar.freebusy.query \
  --input-json '{"timeMin":"2026-10-12T00:00:00Z","timeMax":"2026-10-19T00:00:00Z","items":[{"id":"primary"}]}' \
  --as user:ana
```

```bash
curl https://api.telipot.com/v1/tasks/google-calendar.freebusy.query/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Telipot-Principal: user:ana" \
  -H "Content-Type: application/json" \
  -d '{"timeMin":"2026-10-12T00:00:00Z","timeMax":"2026-10-19T00:00:00Z","items":[{"id":"primary"}]}'
```

## Input

| Field | In | Type | Required | Constraints | Note |
| --- | --- | --- | --- | --- | --- |
| `timeMin` | body | string | yes |  | The start of the interval, an RFC 3339 time with an offset |
| `timeMax` | body | string | yes |  | The end of the interval, an RFC 3339 time with an offset |
| `items` | body | array | yes |  | The calendars to query, each an object with an id from google-calendar.calendars.list, or primary |
| `timeZone` | body | string | no | default "UTC" | The time zone of the times in the answer |
| `calendarExpansionMax` | body | integer | no |  | The most calendars to answer for |

## Input schema

```json
{
  "type": "object",
  "properties": {
    "timeMin": {
      "type": "string",
      "description": "The start of the interval, an RFC 3339 time with an offset",
      "examples": [
        "2026-10-12T00:00:00Z"
      ]
    },
    "timeMax": {
      "type": "string",
      "description": "The end of the interval, an RFC 3339 time with an offset",
      "examples": [
        "2026-10-19T00:00:00Z"
      ]
    },
    "items": {
      "type": "array",
      "description": "The calendars to query, each an object with an id from google-calendar.calendars.list, or primary",
      "examples": [
        [
          {
            "id": "primary"
          }
        ]
      ]
    },
    "timeZone": {
      "type": "string",
      "description": "The time zone of the times in the answer",
      "default": "UTC"
    },
    "calendarExpansionMax": {
      "type": "integer",
      "description": "The most calendars to answer for"
    }
  },
  "required": [
    "timeMin",
    "timeMax",
    "items"
  ],
  "additionalProperties": false
}
```

## Output schema

```json
{
  "type": "object",
  "properties": {
    "timeMin": {
      "type": "string"
    },
    "timeMax": {
      "type": "string"
    },
    "calendars": {
      "type": "object",
      "description": "One entry per queried calendar id",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "busy": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "domain": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "groups": {
      "type": "object"
    },
    "kind": {
      "type": "string"
    }
  }
}
```

## Example response

From `examples/google-calendar.freebusy.query.json`.

```json
{
  "kind": "calendar#freeBusy",
  "timeMin": "2026-10-12T00:00:00.000Z",
  "timeMax": "2026-10-19T00:00:00.000Z",
  "calendars": {
    "contact@example.com": {
      "busy": [
        {
          "start": "2026-10-12T17:00:00Z",
          "end": "2026-10-12T17:30:00Z"
        },
        {
          "start": "2026-10-14T22:00:00Z",
          "end": "2026-10-14T23:00:00Z"
        }
      ]
    }
  }
}
```