> ## 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
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: Search through events with a keyword.
        - schema:
            type: number
            minimum: 1
          in: query
          name: page
          description: Page number for paginated results.
      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?
                            scheduledAt: '2026-04-10T08:30:00.000000Z'
                            utm:
                              utm_campaign: spring_launch
                              utm_source: linkedin
                              utm_medium: social
                              utm_content: null
                              utm_term: 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
                        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: null
                            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
                            scheduledAt: '2026-04-12T11:00:00.000000Z'
                            utm:
                              utm_campaign: null
                              utm_source: null
                              utm_medium: null
                              utm_content: null
                              utm_term: null
                        guests: null
                        hosts:
                          - firstName: Lena
                            lastName: Meier
                            email: lena.meier@horizondigital.de
                            slug: lena-meier
                            url: https://zeeg.me/lena-meier
                            avatarUrl: null
                        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:
                  success:
                    type: boolean
                  message:
                    type: string
                  status:
                    type: integer
              examples:
                Forbidden:
                  value:
                    success: false
                    message: You cannot access this resource.
                    status: 403
        '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
        - 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:
            type: object
            required:
              - fullName
              - email
              - timeZone
              - scheduledAt
            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: Array of additional emails invited
                nullable: true
                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.'
              scheduledAt:
                type: string
                format: date-time
                description: ISO 8601 UTC timestamp when the invitee booked.
                nullable: true
              utm:
                type: object
                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.
              customQueryParams:
                type: array
                items: {}
                description: Custom query parameters captured at booking time.
              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.
          description: Invitees booked on the scheduled event.
        guests:
          type: array
          description: Array of additional emails invited
          nullable: true
          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.
        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.
  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: ''

````