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

# Get Events

> List the Novacal events the authenticated user can access, including scheduling details, attendees, hosts, and current event status.

## What this endpoint returns

This endpoint returns the events the authenticated user hosts or organizes. Use it to review scheduled meetings, sync event data into your own system, or build internal dashboards.

Results are always paginated. The `data` object holds the events for the current page in `data.data`, alongside pagination metadata such as `current_page`, `last_page`, `per_page`, and `total`.

## Filtering and pagination

| Parameter         | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `status`          | `active` returns events that have not been canceled, `canceled` returns canceled events |
| `start`           | Only return events ending on or after this date, for example `2026-07-01`               |
| `end`             | Only return events ending on or before this date. Must be after `start`                 |
| `page`            | The page of results to return. Defaults to `1`                                          |
| `per_page`        | Events per page, between 1 and 100. Defaults to `15`                                    |
| `order_direction` | Sort direction for the event start time, `asc` or `desc`. Defaults to `asc`             |

```bash theme={null}
curl --request GET \
  --url "https://api.novacal.io/v1/events?status=active&start=2026-07-01&end=2026-07-31&per_page=50" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"
```

Paginate by requesting the next page until `next_page_url` is `null`.

## Common use cases

* Load a list of upcoming or past events
* Sync Novacal bookings into a CRM or reporting workflow
* Pull only the bookings for a given month with `start` and `end`
* Reconcile cancellations by requesting `status=canceled`
* Review attendee, host, and event status data before follow-up actions


## OpenAPI

````yaml GET /v1/events
openapi: 3.1.0
info:
  title: Events API
  description: Public API for managing event types
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.novacal.io
security:
  - bearerAuth: []
paths:
  /v1/events:
    get:
      description: >-
        Returns a paginated list of the events the authenticated user hosts or
        organizes. Results can be filtered by status and by date range.
      parameters:
        - name: status
          in: query
          description: >-
            Filter events by status. Use `active` for events that have not been
            canceled, or `canceled` for canceled events.
          required: false
          schema:
            type: string
            enum:
              - active
              - canceled
        - name: start
          in: query
          description: >-
            Only return events that end on or after this date. Accepts any
            parsable date or date-time value, for example `2026-07-01` or
            `2026-07-01 09:00:00`.
          required: false
          schema:
            type: string
            example: '2026-07-01'
        - name: end
          in: query
          description: >-
            Only return events that end on or before this date. Must be after
            `start`. Accepts any parsable date or date-time value.
          required: false
          schema:
            type: string
            example: '2026-07-31'
        - name: page
          in: query
          description: The page of results to return. Defaults to `1`.
          required: false
          schema:
            type: integer
            minimum: 1
            example: 1
        - name: per_page
          in: query
          description: The number of events per page, between 1 and 100. Defaults to `15`.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            example: 15
        - name: order_direction
          in: query
          description: Sort direction for the event start time. Defaults to `asc`.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: Paginated events response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
components:
  schemas:
    EventsResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          description: Indicates whether the request was successful
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/PaginatedEvents'
    PaginatedEvents:
      description: A page of events together with its pagination metadata
      type: object
      properties:
        current_page:
          description: The page number of the returned results
          type: integer
          example: 1
        data:
          description: The events on the current page
          type: array
          items:
            $ref: '#/components/schemas/Event'
        first_page_url:
          description: URL of the first page of results
          type: string
        from:
          description: Index of the first result on the current page
          type:
            - integer
            - 'null'
          example: 1
        last_page:
          description: Number of the last available page
          type: integer
          example: 3
        last_page_url:
          description: URL of the last page of results
          type: string
        links:
          description: Pagination links for rendering page navigation
          type: array
          items:
            type: object
            properties:
              url:
                type:
                  - string
                  - 'null'
              label:
                type: string
              active:
                type: boolean
        next_page_url:
          description: URL of the next page, or null on the last page
          type:
            - string
            - 'null'
        path:
          description: Base path of the paginated endpoint
          type: string
        per_page:
          description: Number of events returned per page
          type: integer
          example: 15
        prev_page_url:
          description: URL of the previous page, or null on the first page
          type:
            - string
            - 'null'
        to:
          description: Index of the last result on the current page
          type:
            - integer
            - 'null'
          example: 15
        total:
          description: Total number of events matching the request
          type: integer
          example: 42
    Event:
      type: object
      properties:
        id:
          description: The unique identifier of the event
          type: string
          format: uuid
        event_type_id:
          description: The identifier of the event type this event was booked from
          type:
            - integer
            - 'null'
          example: 42
        start:
          description: The start date and time of the event
          type: string
          format: date-time
        end:
          description: The end date and time of the event
          type: string
          format: date-time
        canceled_at:
          description: The date and time when the event was canceled
          type:
            - string
            - 'null'
          format: date-time
        cancellation_reason:
          description: The reason the event was canceled, if provided
          type:
            - string
            - 'null'
        location:
          description: The location of the event
          type:
            - string
            - 'null'
        form_field_answers:
          description: >-
            Booking form answers keyed by field identifier. Each value contains
            only the submitted answer.
          type: object
          additionalProperties: true
          example:
            name: John Doe
            email: john@example.com
        status:
          description: The status of the event
          type: string
        name:
          description: The name of the event
          type:
            - string
            - 'null'
        organizer:
          description: The organizer attached to the event
          oneOf:
            - $ref: '#/components/schemas/EventHost'
            - type: 'null'
        hosts:
          description: Hosts attached to the event
          type: array
          items:
            $ref: '#/components/schemas/EventHost'
        booker:
          description: The user who booked the event
          oneOf:
            - $ref: '#/components/schemas/EventBooker'
            - type: 'null'
        guests:
          description: Guest email addresses attached to the event
          type: array
          items:
            type: string
            format: email
        created_at:
          description: The date and time the event was created
          type: string
          format: date-time
        updated_at:
          description: The date and time the event was last updated
          type: string
          format: date-time
    EventHost:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        name:
          type:
            - string
            - 'null'
        email:
          type: string
          format: email
        username:
          type:
            - string
            - 'null'
        timezone:
          type:
            - string
            - 'null'
        time_format:
          type:
            - integer
            - 'null'
          enum:
            - 12
            - 24
            - null
        start_of_week:
          type:
            - integer
            - 'null'
          enum:
            - 0
            - 1
            - null
        avatar:
          type:
            - string
            - 'null'
    EventBooker:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
        email:
          type: string
          format: email
        timezone:
          type:
            - string
            - 'null'
        time_format:
          type:
            - integer
            - 'null'
          enum:
            - 12
            - 24
            - null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````