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

# List Scheduled Events

> Retrieve a paginated list of scheduled events in your Zeeg workspace, with filters for status, date range, host, team, and invitee.



## OpenAPI

````yaml GET /scheduled-events
openapi: 3.0.0
info:
  title: Zeeg Public API
  description: >-
    Zeeg public API documentation.


    ## Authentication

    All endpoints require a Bearer token. You can generate an API token from
    [your Zeeg dashboard](https://app.zeeg.me/account/settings/api-access).


    Each token is scoped to specific permissions (e.g. `events:read`,
    `webhooks:write`). Make sure your token has the required scopes for the
    endpoints you want to use.


    ## Recommended Headers

    We recommend including the `Accept: application/json` header in all API
    requests to ensure you receive JSON responses.
  version: 2.0.0
  x-logo:
    url: https://app.zeeg.me/img/logo-dark.2ca83593.svg
    backgroundColor: '#f7f7f9'
    altText: zeeg
  contact:
    name: Zeeg Support
    email: support@zeeg.me
    url: https://zeeg.me/en/contact
  license:
    name: Proprietary
    url: https://zeeg.me/en/legal/terms
  termsOfService: https://zeeg.me/en/legal/terms
servers:
  - url: https://api.zeeg.me/v2
    description: Production
security:
  - bearer: []
tags:
  - name: Scheduled Events
    description: Management of events scheduled via Zeeg
  - name: Scheduling Pages
    description: Scheduling pages information and management
  - name: Availability Schedule
    description: Read and change availability for users
  - name: Webhooks
    description: Webhooks management
  - name: Notes
    description: Notes for scheduled events
  - name: Workspaces & Teams
    description: Workspace users and team member management
  - name: AI Agent
    description: AI Agent integration endpoints
  - name: Payloads
    description: Webhook payload schemas
  - name: CRM - Objects
    description: >-
      Discover the schema of CRM objects (standard and custom) including all
      attribute definitions
  - name: CRM - Companies
    description: Create, read, update, and delete CRM company records
  - name: CRM - People
    description: Create, read, update, and delete CRM person records
  - name: Routing Forms - Forms
    description: Read routing forms with their questions and their routes
  - name: Routing Forms - Submissions
    description: Read and delete the submissions that invitees send through a routing form
paths:
  /scheduled-events:
    parameters: []
    get:
      tags:
        - Scheduled Events
      summary: List scheduled events
      description: >-
        Returns a list of scheduled events.


        - By default, returns events in which the current user is a host.

        - The **scope** and **userSlug** parameters can be used with an
        organization admin/owner token.

        - If any of the **userSlug**, **teamSlug**, or **hostEmail** parameters
        is set, the **scope** parameter will have no effect.
      operationId: get-api-scheduled-events
      parameters:
        - schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
          in: query
          name: sort
          description: Order results based on the startTime.
        - schema:
            type: number
            default: 20
            minimum: 1
            maximum: 100
          in: query
          name: count
          description: Limit the number of returned results per page.
          allowReserved: false
          allowEmptyValue: false
        - schema:
            type: string
            enum:
              - confirmed
              - cancelled
          in: query
          name: status
          description: >-
            Filter based on event status. Possible values are: active,
            cancelled. Omit for all events.
        - schema:
            type: string
            format: date-time
            example: '2026-04-01T00:00:00.000000Z'
          in: query
          name: minStartTime
          description: Filter for events starting after the specified time.
        - schema:
            type: string
            format: date-time
            example: '2026-04-30T23:59:59.000000Z'
          in: query
          name: maxStartTime
          description: Filter for events starting before the specified time.
        - schema:
            type: string
            enum:
              - all
          in: query
          name: scope
          description: >-
            Filters results based on the scope. Currently only 'all' is
            supported, returning all events of the whole organization. More
            options coming soon.
        - schema:
            type: string
            example: lena-meier
          in: query
          name: userSlug
          description: >-
            Filter for events hosted by a specific user in your organization
            based on the user's slug.
        - schema:
            type: string
            format: email
            example: lena.meier@horizondigital.de
          in: query
          name: hostEmail
          description: >-
            Filter for events hosted by a specific user in your organization
            based on the user's email address.
        - schema:
            type: string
            format: email
            example: sophie.laurent@northwind.io
          in: query
          name: inviteeEmail
          description: Filter for events of a specific invitee by their email address.
        - schema:
            type: string
          in: query
          name: teamSlug
          description: >-
            Filter for events that belong to a specific team in your
            organization based on the team's slug.
        - schema:
            type: string
          in: query
          name: keyword
          description: >-
            Case-insensitive search across the invitee name, the invitee email,
            the answers to booking questions, and the values of custom query
            parameters. The keyword matches any part of a field, and an event is
            returned if any of its confirmed invitees matches. Custom query
            parameter names are not searched, only their values. For
            reconciliation, use `customQueryParams` instead: the keyword matches
            partial text, so `EYE-PROBE-0002` also returns an event tagged
            `EYE-PROBE-00021`.
        - schema:
            type: object
            additionalProperties:
              type: string
              maxLength: 100
            example:
              c__ticket: EYE-PROBE-0002
          in: query
          style: deepObject
          explode: true
          name: customQueryParams
          description: >-
            Filter for events whose custom query parameter carries exactly this
            value. The value must match in full, so `EYE-PROBE-0002` never
            returns an event tagged `EYE-PROBE-00021`. Write the parameter name
            with or without its `c__` prefix — `c__ticket` and `ticket` name the
            same parameter, because every name here is one. Combine at most
            three parameters across `customQueryParams` and
            `hasCustomQueryParams`; they are AND-ed. Example:
            `?customQueryParams[c__ticket]=EYE-PROBE-0002`. Send an empty value
            to match the events tagged with an empty one. Values are stored with
            any HTML tags removed, so match against the stored value: a booking
            tagged `size<10` is stored as `size`.
        - schema:
            type: array
            items:
              type: string
              maxLength: 100
            maxItems: 3
            example:
              - c__region
          in: query
          style: deepObject
          explode: true
          name: hasCustomQueryParams
          description: >-
            Filter for events that carry the named custom query parameter at any
            value, including an empty one. The name takes the `c__` prefix or
            leaves it off, as in `customQueryParams`. Counts towards the same
            limit of three as `customQueryParams`. Repeat the name in brackets —
            `?hasCustomQueryParams[]=c__region`, or the indexed form
            `?hasCustomQueryParams[0]=c__region`. A bare repeated key
            (`?hasCustomQueryParams=a&hasCustomQueryParams=b`) collapses to the
            last value and is rejected.
        - schema:
            type: number
            minimum: 1
          in: query
          name: page
          description: Page number for paginated results.
        - schema:
            type: string
          in: query
          name: eventTypeId
          description: >-
            Filter for events that belong to a specific event type, identified
            by its ID.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - pagination
                properties:
                  collection:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScheduledEvent'
                  pagination:
                    type: object
                    required:
                      - total
                      - count
                      - totalPages
                      - currentPage
                    properties:
                      total:
                        type: integer
                        minimum: 0
                        description: Total number of records.
                      count:
                        type: integer
                        minimum: 0
                        default: 20
                        description: Number of records per page.
                      totalPages:
                        type: integer
                        minimum: 0
                        description: Total number of pages.
                      previousPage:
                        type: string
                        nullable: true
                        description: Link to previous page, or null.
                        example: /v2/scheduled-events?page=1
                      currentPage:
                        type: integer
                        minimum: 1
                        description: Current page number.
                      nextPage:
                        type: string
                        nullable: true
                        description: Link to next page, or null.
                        example: /v2/scheduled-events?page=3
              examples:
                List of scheduled events:
                  value:
                    collection:
                      - uri: >-
                          https://api.zeeg.me/v2/scheduled-events/zg-O69bac566950c6
                        uuid: zg-O69bac566950c6
                        title: 30-Minute Discovery Call
                        type: ONE_ON_ONE
                        startTime: '2026-04-15T09:00:00.000000Z'
                        endTime: '2026-04-15T09:30:00.000000Z'
                        duration: 30
                        status: confirmed
                        eventTypeUri: >-
                          https://api.zeeg.me/v2/event-types/80f46bf5-eb01-4c07-960e-a9a3e18aae5e
                        location:
                          type: Google Meet
                          joinUrl: https://meet.google.com/abc-defg-hij
                        maxActiveInvitees: 1
                        activeInviteesCount: 1
                        invitees:
                          - uuid: zg-O69bad4047abf0
                            salutation: Ms.
                            fullName: Sophie Laurent
                            email: sophie.laurent@northwind.io
                            guests:
                              - alex.chen@northwind.io
                            timeZone: Europe/Paris
                            cancellation:
                              cancelledAt: null
                              cancelledBy: null
                              cancellerType: null
                              cancellationReason: null
                            payment: null
                            questions:
                              - answer: Product demo and pricing options
                                answer_type: STRING
                                question: What would you like to discuss?
                            noShow: false
                            noShowAt: null
                            scheduledAt: '2026-04-10T08:30:00.000000Z'
                            utm:
                              utm_campaign: spring_launch
                              utm_source: linkedin
                              utm_medium: social
                              utm_content: null
                              utm_term: null
                            customQueryParams:
                              c__ref: nl-2026-04
                            cancelUrl: https://zeeg.me/cancel/zg-O69bad4047abf0
                            rescheduleUrl: https://zeeg.me/reschedule/zg-O69bad4047abf0
                            rescheduled: false
                            rescheduling: null
                            nextRescheduling: null
                        guests:
                          - alex.chen@northwind.io
                        hosts:
                          - firstName: Lena
                            lastName: Meier
                            email: lena.meier@horizondigital.de
                            slug: lena-meier
                            url: https://zeeg.me/lena-meier
                            avatarUrl: null
                        teamName: Sales
                        createdAt: '2026-04-10T08:30:00.000000Z'
                        updatedAt: '2026-04-10T08:30:02.000000Z'
                        currentTime: '2026-03-23T10:00:00.000000Z'
                      - uri: >-
                          https://api.zeeg.me/v2/scheduled-events/zg-O69bad4047abf0
                        uuid: zg-O69bad4047abf0
                        title: 30-Minute Discovery Call
                        type: ONE_ON_ONE
                        startTime: '2026-04-18T14:00:00.000000Z'
                        endTime: '2026-04-18T14:30:00.000000Z'
                        duration: 30
                        status: cancelled
                        eventTypeUri: >-
                          https://api.zeeg.me/v2/event-types/80f46bf5-eb01-4c07-960e-a9a3e18aae5e
                        location:
                          type: Google Meet
                          joinUrl: https://meet.google.com/klm-nopq-rst
                        maxActiveInvitees: 1
                        activeInviteesCount: 0
                        invitees:
                          - uuid: zg-O69bac566950c6
                            salutation: null
                            fullName: Marco Rossi
                            email: marco.rossi@horizondigital.de
                            guests: []
                            timeZone: Europe/Berlin
                            cancellation:
                              cancelledAt: '2026-04-17T10:00:00.000000Z'
                              cancelledBy: marco.rossi@horizondigital.de
                              cancellerType: host
                              cancellationReason: Schedule conflict with another commitment.
                            payment: null
                            questions: null
                            noShow: false
                            noShowAt: null
                            scheduledAt: '2026-04-12T11:00:00.000000Z'
                            utm:
                              utm_campaign: null
                              utm_source: null
                              utm_medium: null
                              utm_content: null
                              utm_term: null
                            customQueryParams: {}
                            cancelUrl: null
                            rescheduleUrl: null
                            rescheduled: true
                            rescheduling: null
                            nextRescheduling:
                              oldStartAt: '2026-04-18T14:00:00.000000Z'
                              newStartAt: '2026-04-22T09:30:00.000000Z'
                              rescheduledAt: '2026-04-17T10:00:00.000000Z'
                              previousEventUuid: zg-O69bad4047abf0
                              previousInviteeUuid: zg-O69bac566950c6
                              reason: Requested a later slot.
                              rescheduledBy: invitee
                              reschedulerFullName: null
                        guests: []
                        hosts:
                          - firstName: Lena
                            lastName: Meier
                            email: lena.meier@horizondigital.de
                            slug: lena-meier
                            url: https://zeeg.me/lena-meier
                            avatarUrl: null
                        teamName: Sales
                        createdAt: '2026-04-12T11:00:00.000000Z'
                        updatedAt: '2026-04-17T10:00:00.000000Z'
                        currentTime: '2026-03-23T10:00:00.000000Z'
                    pagination:
                      total: 2
                      count: 2
                      totalPages: 1
                      previousPage: null
                      currentPage: 1
                      nextPage: null
        '401':
          $ref: '#/components/responses/401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                      message:
                        type: string
                      error_id:
                        type: string
                      required_scopes:
                        type: array
                        items:
                          type: string
              examples:
                Missing scope:
                  value:
                    error:
                      type: insufficient_scope
                      message: >-
                        Your token is missing the required scope(s). Include at
                        least one of: events:read, events:write.
                      error_id: 9cfa47d0-d633-44ba-b3a8-0845d4fca38a
                      required_scopes:
                        - events:read
                        - events:write
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
              examples:
                Invalid status value:
                  value:
                    message: The selected status is invalid.
                    errors:
                      status:
                        - The selected status is invalid.
      security:
        - bearer: []
components:
  schemas:
    ScheduledEvent:
      type: object
      required:
        - uri
        - uuid
        - title
        - type
        - startTime
        - endTime
        - duration
        - status
        - eventTypeUri
        - maxActiveInvitees
        - activeInviteesCount
        - invitees
        - teamName
        - createdAt
      properties:
        uri:
          type: string
          format: uri
          description: Public API URI of the scheduled event resource.
        uuid:
          type: string
          description: Zeeg event identifier (zg-XXX format)
          example: zg-O69bac566950c6
        title:
          type: string
          description: Title of the scheduled event.
        type:
          type: string
          description: Event type kind (e.g. `ONE_ON_ONE`, `GROUP`, `ROUND_ROBIN`).
        startTime:
          type: string
          format: date-time
          description: ISO 8601 UTC start time of the booked event.
        endTime:
          type: string
          format: date-time
          description: ISO 8601 UTC end time of the booked event.
        duration:
          type: integer
          description: Event duration in minutes.
        status:
          type: string
          description: Booking status (e.g. `confirmed`, `cancelled`).
        eventTypeUri:
          type: string
          format: uri
          description: Public API URI of the event type this booking was made against.
        location:
          type: object
          nullable: true
          required:
            - type
          properties:
            type:
              type: string
              description: >-
                Location type (e.g. `google_meet`, `zoom`, `phone`,
                `in_person`).
            joinUrl:
              type: string
              format: uri
              description: Join URL for the meeting, when applicable.
              nullable: true
          description: Meeting location for the booking.
        maxActiveInvitees:
          type: integer
          description: Maximum number of active invitees the event allows.
        activeInviteesCount:
          type: integer
          description: Current number of active (non-cancelled) invitees.
        invitees:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledInvitee'
          description: Invitees booked on the scheduled event.
        guests:
          type: array
          description: >-
            Email addresses of additional guests added across all invitees. An
            empty array when none were added.
          items:
            type: string
        hosts:
          type: array
          nullable: true
          items:
            type: object
            required:
              - firstName
              - email
              - slug
              - url
            properties:
              firstName:
                type: string
                description: Host's first name.
                nullable: true
              lastName:
                type: string
                description: Host's last name. Empty string when not set.
              email:
                type: string
                format: email
                description: Host's email address.
                nullable: true
              slug:
                type: string
                description: Host's public profile slug.
                nullable: true
              url:
                type: string
                format: uri
                description: Host's public profile URL.
              avatarUrl:
                type: string
                format: uri
                nullable: true
                description: URL of the host's avatar image, if set.
          description: Hosts assigned to the scheduled event.
        teamName:
          type: string
          nullable: true
          description: >-
            Name of the team that owns the scheduling page the booking was made
            on, or `null` for a personal scheduling page. The key is always
            present. This is the same value the `invitee.scheduled` webhook
            sends as `teamName` for the same booking.
          example: Sales
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the booking was created.
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the booking was last updated.
        currentTime:
          type: string
          format: date-time
          description: Current server time
      description: >-
        A scheduled event resource. This is the single canonical shape returned
        by all scheduled-event endpoints and embedded in the AI agent call
        webhook payload.
    ScheduledInvitee:
      type: object
      required:
        - fullName
        - email
        - timeZone
        - scheduledAt
        - noShow
      properties:
        uuid:
          type: string
          description: Zeeg attendee identifier (zg-XXX format)
          example: zg-O69bac566950c6
        salutation:
          type: string
          nullable: true
          description: Salutation for the invitee, if collected.
        fullName:
          type: string
          description: Full name of the invitee.
          nullable: true
        email:
          type: string
          format: email
          description: Email address of the invitee.
          nullable: true
        guests:
          type: array
          description: >-
            Email addresses of additional guests the invitee added. An empty
            array when the invitee added none.
          items:
            type: string
        timeZone:
          type: string
          description: IANA time zone of the invitee.
          nullable: true
        cancellation:
          type: object
          properties:
            cancelledAt:
              type: string
              format: date-time
              nullable: true
              description: ISO 8601 UTC timestamp when the invitee was cancelled.
            cancelledBy:
              type: string
              nullable: true
              description: Identifier of who cancelled the booking.
            cancellerType:
              type: string
              nullable: true
              description: Type of canceller (e.g. host, invitee).
            cancellationReason:
              type: string
              nullable: true
              description: Reason given for the cancellation.
          description: >-
            Cancellation details. All fields are `null` when the invitee is not
            cancelled.
        payment:
          type: object
          nullable: true
          description: Payment details for the booking, or `null` when no payment applies.
          properties:
            gateway:
              type: string
              description: Payment provider, e.g. `stripe` or `paypal`.
            price:
              type: number
            currency:
              type: string
            transactionId:
              type: string
              nullable: true
            createdAt:
              type: string
              format: date-time
            status:
              type: string
              enum:
                - pending
                - success
              description: '`pending` until the transaction completes.'
        noShow:
          type: boolean
          description: Whether the invitee has been marked as a no-show. Always present.
        noShowAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 UTC timestamp when the invitee was marked as a no-show, or
            `null` when they were not.
        scheduledAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the invitee booked.
          nullable: true
        utm:
          type: object
          required:
            - utm_campaign
            - utm_source
            - utm_medium
            - utm_term
            - utm_content
          properties:
            utm_campaign:
              type: string
              nullable: true
            utm_source:
              type: string
              nullable: true
            utm_medium:
              type: string
              nullable: true
            utm_content:
              type: string
              nullable: true
            utm_term:
              type: string
              nullable: true
          description: >-
            UTM tracking parameters captured at booking time. Always holds these
            five keys, in `snake_case`; a key holds `null` when the booking did
            not carry a value for it.
        adAttribution:
          type: object
          nullable: true
          properties:
            gclid:
              type: string
              nullable: true
              description: Google Ads click ID.
            gbraid:
              type: string
              nullable: true
              description: >-
                Google click ID for iOS app-to-web clicks. Mutually exclusive
                with `gclid` per click.
            wbraid:
              type: string
              nullable: true
              description: >-
                Google click ID for web-to-app clicks. Mutually exclusive with
                `gclid` per click.
            fbclid:
              type: string
              nullable: true
              description: Meta click ID.
            fbp:
              type: string
              nullable: true
              description: Meta browser ID cookie (`_fbp`) captured at booking time.
            fbc:
              type: string
              nullable: true
              description: Meta click cookie (`_fbc`) captured at booking time.
            landingUrl:
              type: string
              nullable: true
              description: Full URL of the host page the booking widget was embedded on.
          description: >-
            Ad-click identifiers captured at booking time, keyed by provider.
            Only the keys that were actually captured are present; `null` when
            none were captured.
        customQueryParams:
          type: object
          description: >-
            Custom query parameters captured at booking time, keyed by the
            `c__`-prefixed parameter name. An empty object when the booking
            captured none.
          example:
            c__ref: nl-2026-04
        questions:
          type: array
          nullable: true
          items:
            type: object
            properties:
              answer:
                type: string
              answer_type:
                type: string
              question:
                type: string
          description: Booking questions answered by the invitee.
        agentBookingReference:
          type: string
          nullable: true
          description: Reference code for bookings made via the AI agent; `null` otherwise.
        cancelUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            Public URL the invitee uses to cancel this booking. `null` once the
            booking is cancelled.
        rescheduleUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            Public URL the invitee uses to reschedule this booking. `null` once
            the booking is cancelled.
        rescheduled:
          type: boolean
          description: >-
            True once this booking has been superseded by a reschedule. A
            rescheduled booking reports `status: cancelled` for backward
            compatibility; `rescheduled` and `nextRescheduling` are how a caller
            tells a reschedule apart from an actual cancellation.
        rescheduling:
          allOf:
            - $ref: '#/components/schemas/EventRescheduling'
          nullable: true
          description: >-
            Present when this booking is the *result* of a reschedule. `null`
            when this booking was not itself created by rescheduling an earlier
            one.
        nextRescheduling:
          allOf:
            - $ref: '#/components/schemas/EventRescheduling'
          nullable: true
          description: >-
            Present when this booking has been superseded by a later reschedule.
            `null` when the booking has not been rescheduled.
      description: >-
        One invitee of a scheduled event. The scheduled event embeds it in
        `invitees`, and the invitee endpoints return it as `resource`.
    EventRescheduling:
      type: object
      description: >-
        Links one half of a reschedule to the other. Embedded as `rescheduling`
        (on the new booking) and `nextRescheduling` (on the superseded booking)
        inside an invitee.
      properties:
        oldStartAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 UTC start time the previous booking held before the
            reschedule.
        newStartAt:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 UTC start time the new booking was moved to.
        rescheduledAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the reschedule was performed.
        previousEventUuid:
          type: string
          nullable: true
          description: >-
            uuid of the superseded booking (zg-XXX format). Use it directly as
            the `uuid` path parameter of `GET /scheduled-events/{uuid}` to fetch
            that booking.
          example: zg-O69bad4047abf0
        previousInviteeUuid:
          type: string
          nullable: true
          description: >-
            uuid of the invitee on the superseded booking. No public endpoint
            accepts an invitee uuid as a path parameter.
          example: zg-O69bac566950c6
        reason:
          type: string
          nullable: true
          description: Reason given for the reschedule, if any.
        rescheduledBy:
          type: string
          nullable: true
          description: Who performed the reschedule (e.g. `host`, `invitee`).
        reschedulerFullName:
          type: string
          nullable: true
          description: Full name of the person who performed the reschedule, when known.
  responses:
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthenticated.
          examples:
            Unauthenticated:
              value:
                message: Unauthenticated.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: ''

````

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