---
title: "List events"
method: GET
path: "/v1/events"
tags: ["Events"]
---

# List events

`GET /v1/events`

## Request

- Base URL: `https://api.savvycal.com`
- URL: `https://api.savvycal.com/v1/events`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Token URL: `/oauth/token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/savvycal/apis/savvycal-meetings-api/docs/v1/events/get.ts> (a function with typed inputs; its response is checked against the schema)

When any filter value is invalid, such as an unparseable date, every filter uses its default.

## Query parameters

- `limit` integer
- `after` string
- `before` string
- `state` 'all' | 'any' | 'confirmed' | 'canceled' | 'awaiting_reschedule' | 'awaiting_checkout' | 'checkout_expired' | 'awaiting_approval' | 'declined' | 'tentative'
- `period` 'past' | 'upcoming' | 'fixed' | 'all'
- `from` string, date
- `until` string, date
- `time_zone` string
- `q` string
- `direction` 'asc' | 'desc'
- `attendance` 'attending' | 'any'
- `link` string

## Response `200`

Success

- EventListResponse
  - `entries` Event[], required
    - `canceled_at` string, date-time, nullable
    - `rescheduled_at` string, date-time, nullable
    - `location_settings` object[]: Each entry has a `type` and that type's settings.
      - `type` string, required
    - `description_settings` object, required: Which details the calendar event description includes
      - `include_attendees` boolean, required
      - `include_fields` boolean, required
      - `include_link_name` boolean, required
    - `location` string, nullable: The location on the calendar event: the event's location, or else the conferencing join URL or instructions.
    - `buffer_before` integer, required: Buffer before the event, in minutes
    - `additional_info` string, nullable
    - `duration` integer, required: Duration in minutes
    - `uuid` string, uuid, required
    - `reschedule_reason` string, nullable
    - `conferencing` object, required
      - `instructions` string, nullable
      - `join_url` string, nullable
      - `meeting_id` string, nullable
      - `type` string, required
    - `link` LinkPreview
      - `description` string, required: Link description, as HTML. Empty when the link has no description.
      - `id` string, required
      - `name` string, required
      - `private_name` string, nullable, required: Private link name. `null` when the current user can't edit the link or the link has no private name.
      - `slug` string, required
    - `poll` PollPreview
      - `id` string, required
      - `name` string, required
      - `slug` string, required
    - `summary` string, required: Event title
    - `original_end_at` string, date-time, nullable: Original end time (if rescheduled)
    - `description` string: The scheduling link's description at the time of booking, as HTML. Empty when there is no description.
    - `id` string, required
    - `cancel_reason` string, nullable
    - `organizer` EventAttendee, required
      - `display_name` string, required
      - `email` string, required
      - `fields` EventField[], required: The attendee's answers to the scheduling link's custom fields
        - `id` string, required
        - `label` string, required
        - `options` FieldOption[], required: The selected options for a `checkboxes`, `radios`, or `select` field. Empty for other field types.
          - `id` string, required
          - `value` string, required
        - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
        - `value` string, nullable, required: The answer as text. For a `checkboxes` field, the selected option values joined by newlines. `null` when the field has no answer.
      - `first_name` string, required: The first word of `display_name`
      - `id` string, required
      - `is_organizer` boolean, required
      - `last_name` string, required: The rest of `display_name`. Empty when `display_name` is one word.
      - `marketing_opt_in` boolean, required
      - `phone_number` string, nullable
      - `response_status` 'accepted' | 'tentative' | 'needs_action' | 'declined', required
      - `time_zone` string, required
    - `is_group_session` boolean, nullable, required: Whether this is a group session. `null` on some older events.
    - `original_start_at` string, date-time, nullable: Original start time (if rescheduled)
    - `start_at` string, date-time, required
    - `url` string, uri, required: Public URL for the event
    - `payment` Payment
      - `amount_total` integer, nullable, required: Total amount charged (in cents)
      - `state` 'awaiting_checkout' | 'paid', required
      - `url` string, uri, nullable, required: A link to the Stripe dashboard page for the payment (only available after checkout is completed)
    - `maximum_group_size` integer, nullable, required: Maximum number of attendees for group session. `null` for events booked from a poll.
    - `end_at` string, date-time, required
    - `state` 'confirmed' | 'canceled' | 'awaiting_reschedule' | 'awaiting_checkout' | 'checkout_expired' | 'awaiting_approval' | 'declined' | 'tentative', required
    - `attendees` EventAttendee[], required
      - `display_name` string, required
      - `email` string, required
      - `fields` EventField[], required: The attendee's answers to the scheduling link's custom fields
        - `id` string, required
        - `label` string, required
        - `options` FieldOption[], required: The selected options for a `checkboxes`, `radios`, or `select` field. Empty for other field types.
          - `id` string, required
          - `value` string, required
        - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
        - `value` string, nullable, required: The answer as text. For a `checkboxes` field, the selected option values joined by newlines. `null` when the field has no answer.
      - `first_name` string, required: The first word of `display_name`
      - `id` string, required
      - `is_organizer` boolean, required
      - `last_name` string, required: The rest of `display_name`. Empty when `display_name` is one word.
      - `marketing_opt_in` boolean, required
      - `phone_number` string, nullable
      - `response_status` 'accepted' | 'tentative' | 'needs_action' | 'declined', required
      - `time_zone` string, required
    - `scheduler` EventAttendee
      - `display_name` string, required
      - `email` string, required
      - `fields` EventField[], required: The attendee's answers to the scheduling link's custom fields
        - `id` string, required
        - `label` string, required
        - `options` FieldOption[], required: The selected options for a `checkboxes`, `radios`, or `select` field. Empty for other field types.
          - `id` string, required
          - `value` string, required
        - `type` 'short_text' | 'long_text' | 'checkboxes' | 'radios' | 'select' | 'url' | 'hidden', required
        - `value` string, nullable, required: The answer as text. For a `checkboxes` field, the selected option values joined by newlines. `null` when the field has no answer.
      - `first_name` string, required: The first word of `display_name`
      - `id` string, required
      - `is_organizer` boolean, required
      - `last_name` string, required: The rest of `display_name`. Empty when `display_name` is one word.
      - `marketing_opt_in` boolean, required
      - `phone_number` string, nullable
      - `response_status` 'accepted' | 'tentative' | 'needs_action' | 'declined', required
      - `time_zone` string, required
    - `scope` ScopePreview: Preview of a scope/team
      - `id` string, required
      - `name` string, required
      - `slug` string, required
    - `buffer_after` integer, required: Buffer after the event, in minutes
    - `metadata` object, required: The custom `metadata` sent when the event was created.
    - `created_at` string, date-time, required
  - `metadata` PaginationMeta, required
    - `after` string, nullable: Pass as `after` to get the next page. `null` on the last page.
    - `before` string, nullable: Pass as `before` to get the previous page. `null` on the first page.
    - `limit` integer, required

## Other responses

- `400`: Invalid `after` or `before` cursor
- `401`: Unauthorized

---

[API](https://skmtc.dev/savvycal/apis/savvycal-meetings-api.md) - [All operations](https://skmtc.dev/savvycal/apis/savvycal-meetings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/savvycal/apis/savvycal-meetings-api/revisions/398985d699a3?raw)