# Get all group events

> **GET** `https://api.us.nylas.com/v3/grants/{grant_id}/scheduling/configurations/{configuration_id}/group-events`

Source: https://developer.nylas.com/docs/reference/api/group-events/get-group-events/

Returns all group events within the given time range, from the specified Configuration.

**Authentication:** NYLAS_API_KEY

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `calendar_id` | string | Yes | Filter for the specified calendar ID.  (Not supported for iCloud) You can use `primary` to query the user's primary calendar. |
| `start_time` | integer | Yes | Filter for events that start at or after the specified time, in seconds using the Unix timestamp format. For example, if you filter for events that start at 9:00a.m. and the calendar includes an event that runs from 8:30–9:30a.m., Nylas returns that event. |
| `end_time` | integer | Yes | Filter for events that end at or before the specified time, in seconds using the Unix timestamp format. For example, if you filter for events that end at 5:00p.m. and the calendar includes an event that runs from 4:30–5:30p.m., Nylas returns that event. |

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | The ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. |
| `configuration_id` | string | Yes | The ID of the Configuration object to access. |

## Responses

### 200 - Group events returned

- `request_id` (string) - The request ID.
- `data` (array)
  - `capacity` (integer) - (Not supported for EWS events) The maximum number of attendees allowed in the event.
  - `conferencing` (object) - An object that lets you automatically create a conference, or enter conferencing details manually.

You can't use `autocreate` and `details` in the same request. If you do, Nylas returns an error.

Nylas stores conference information in the event description. To remove conference details, set
`conferencing` to `{}` and remove the corresponding conference information from the description in
the same request.
    - **Auto-conferencing**
      - `provider` (string) - The conferencing provider that Nylas uses to create the conference.
      - `autocreate` (object) - When you include `autocreate` in your request, Nylas automatically creates conferencing
details for the event.

If you specify a conferencing provider that isn't available to your user's account, you need
to include the `conf_grant_id` that belongs to a provider with the supported conference type.
For example, if you specify the `provider` is `Google Meet` and the user authenticated with
a Microsoft account, you need to define the `conf_grant_id`. If the `provider` is
`Zoom Meeting`, you always need to specify a `conf_grant_id`.

When you specify a `conf_grant_id`, the user that belongs to the specified grant ID acts as
a conference host. They need to join the conference at the scheduled time and admit other
participants during the meeting.

If the `provider` is `Zoom Meeting`, your Zoom OAuth app must include the following
[granular scopes](https://developers.zoom.us/docs/integrations/oauth-scopes-granular/)
for Nylas to manage meetings on behalf of the user:

- `meeting:write:meeting` — required to **create** Zoom meetings.
- `meeting:update:meeting` — required to **update** Zoom meetings (for example, when event time or title changes).
- `meeting:delete:meeting` — required to **delete** Zoom meetings (when events are removed).

If any of these scopes are missing, the Zoom API rejects the request. After adding scopes
to your Zoom app, affected users must re-authenticate their grant so their access tokens
include the new scopes.

If the `provider` is `Zoom Meeting`, you can include the `conf_settings` object in your
request. It contains a `settings` property where you can pass parameters from
[Zoom's Create a Meeting API](https://developers.zoom.us/docs/api/rest/reference/zoom-api/methods/#operation/meetingCreate).
These settings make your Zoom integration more accessible, but potentially less secure. We
recommend you review your organization's security requirements.

You can include other provider settings in `autocreate.settings`, but Nylas does _not_
validate them.
    - **Google Meet**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains Google Meet conferencing details.
        - `url` (string) **(required)** - The URL for the Google Meet conference.
        - `phone` (array) - The phone number associated with the Google Meet conference. This array accepts only
one phone number.
        - `pin` (string) - The PIN associated with the Google Meet conference, if applicable.
    - **Zoom Meeting**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains Zoom conferencing details.
        - `url` (string) **(required)** - The URL for the Zoom conference.
        - `meeting_code` (string,null) - A unique ID associated with the Zoom conference.
        - `password` (string,null) - The password for the Zoom conference, if applicable.
    - **Microsoft Teams**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains Microsoft Teams conferencing details.
        - `url` (string) **(required)** - The URL for the Microsoft Teams conference.
    - **Teams for Business**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains Microsoft Teams for Enterprise conferencing details.
        - `url` (string) **(required)** - The URL for the Microsoft Teams for Enterprise conference.
    - **Skype for Consumer**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains Skype for Consumer conferencing details.
        - `url` (string) **(required)** - The URL for the Skype for Consumer conference.
    - **Skype for Business**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains Skype for Business conferencing details.
        - `url` (string) **(required)** - The URL for the Skype for Business conference.
    - **WebEx**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains WebEx conferencing details.
        - `url` (string) **(required)** - The URL for the WebEx conference.
        - `password` (string) - The password for the WebEx conference, if applicable.
        - `pin` (string) - The PIN for the WebEx conference, if applicable.
        - `phone` (array) - The phone number associated with the WebEx conference.
    - **GoToMeeting**
      - `provider` (string) - The conferencing provider for the event.
      - `details` (object) - An object that contains GoToMeeting conferencing details.
        - `url` (string) **(required)** - The URL for the GoToMeeting conference.
        - `meeting_code` (string) - A unique ID associated with the GoToMeeting conference.
        - `password` (string) - The password for the GoToMeeting conference, if applicable.
        - `phone` (array) - The phone number associated with the GoToMeeting conference.
  - `description` (string) - A brief description of the group event (for example, its agenda). Nylas might return the
description as an HTML string, depending on how the provider formats it.

For Google accounts, this field accepts a maximum of 8,192 characters.
  - `location` (string) - The location of the group event (for example, a physical address or the name of a meeting
room).
  - `participants` (array) **(required)**
    - `name` (string) - The participant's name.
    - `email` (string) **(required)** - The participant's email address.
    - `is_organizer` (boolean) - When `true`, indicates that the participant is the event organizer.
  - `recurrence` (array) - An array of `RRULE` and `EXDATE` strings. Nylas includes this field only if the event is the main
(master) event. See [RFC-5545](https://tools.ietf.org/html/rfc5545#section-3.8.5) for more details.
You can use [this tool](https://jkbrzt.github.io/rrule/) to learn more about the `RRULE` spec.

Events inherit their timezone from the `when` object. Nylas recommends that you use the `when`
object to specify the event's start and end time.

Provider specifics:
  - Virtual calendars don't support `DTSTART` or `TZID`.
  - iCloud accounts do _not_ support recurring events for group events
  - Microsoft Graph adds one day to the `UNTIL` date.
  - `reminders` (array)
    - `type` (string) - The reminder type.
    - `minutes_before_event` (integer) - The number of minutes before the event to send the reminder.
    - `recipient` (string) - (Email reminders only) Who should receive the reminder.
    - `email_subject` (string) - (Email reminders only) The subject line of the email reminder.
  - `title` (string) - The name of the event.
  - `when` (object) **(required)** - The time and duration of the event.
    - **Timespan**
      - `start_time` (integer) - The event's start time, in seconds using the Unix timestamp format.
      - `end_time` (integer) - The event's end time, in seconds using the Unix timestamp format.
      - `start_timezone` (string,null) - The timezone of the event's `start_time` as an
[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.

If you define `start_timezone` in your request, you must also define `end_timezone`.
      - `end_timezone` (string,null) - The timezone of the event's `end_time` as an
[IANA-formatted](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string.

If you define `end_timezone` in your request, you must also define `start_timezone`.
    - **Read-only object**
- `next_cursor` (string,null) - A cursor pointing to the next page of results for the request.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 504 - Provider Failure

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --compressed --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIG_ID>/group-events"?calendar_id=<CALENDAR_ID>&start_time=<TIMESTAMP>&end_time=<TIMESTAMP>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'
```