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

# List events

`GET /events`

## Request

- Base URL: `https://joinways.app/api/v1`
- URL: `https://joinways.app/api/v1/events`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://joinways.app/oauth/authorize`, token URL `https://joinways.app/api/oauth/token`, scopes: `mcp.read`)

Events of the workspace, newest start date first by default. Archived events are left out unless `archived` says otherwise. The sample events created at onboarding are never listed. Amounts are `null` without `reports.view` or `quotes.manage`. **Role permission:** none (any member).

## Query parameters

- `page` integer
- `per_page` integer
- `sort` 'start_date' | 'created_at' | 'title' | 'status' | 'company_name'
- `order` 'asc' | 'desc'
- `status` EventStatus[]
- `type` string[]
- `company_id` string, uuid
- `venue_id` string, uuid
- `from` string, date
- `to` string, date
- `q` string
- `archived` 'exclude' | 'only' | 'all'

## Response `200`

Page of events. A page past the last one is empty.

- object: Envelope wrapping a page of results.
  - `data` EventSummary[], required: The page of results (item type depends on the endpoint).
    - `id` string, uuid
    - `event_number` integer, nullable
    - `internal_reference` string, nullable
    - `title` string
    - `type` string, nullable: Event type, e.g. dinner, wedding, seminar, cocktail.
    - `category` string, nullable
    - `status` 'option' | 'confirmed' | 'lost' | 'cancelled': `option` = pending / tentative, `confirmed` = booked, `lost` = did not convert, `cancelled` = cancelled after booking.
    - `pax` integer, nullable: Number of guests.
    - `start_date` string, date-time
    - `end_date` string, date-time, nullable
    - `selected_dates` string[], nullable: Explicit non-contiguous days of a multi-day event that skips days. When set, `start_date` / `end_date` are the envelope; `null` means a plain contiguous range.
    - `day_hours` DayHoursEntry[], nullable: Per-day hours of a multi-day event, by date: one entry per day when the days have different hours, `null` when every day has the same hours (the time of `start_date` to the time of `end_date`) or for a one-day event.
      - `date` string, date, required
      - `start` string, required
      - `end` string, required
    - `timezone` string, nullable
    - `flexible` boolean, nullable: Whether the client's dates are flexible.
    - `language` string, nullable
    - `budget` number, nullable: Client budget. `null` without revenue access.
    - `expected_revenue` number, nullable: Expected revenue. `null` without revenue access.
    - `confirmed_amount_excl_tax` number, nullable: Confirmed amount excl. tax. `null` without revenue access.
    - `confirmed_at` string, date-time, nullable
    - `currency` string, nullable
    - `venue_id` string, uuid, nullable: The venue (internally `location_id`).
    - `venue_name` string, nullable
    - `location_type` string, nullable
    - `location_city` string, nullable
    - `location_color` string, nullable
    - `company_id` string, uuid, nullable
    - `company_name` string, nullable
    - `contact_person_id` string, uuid, nullable
    - `contact_first_name` string, nullable
    - `contact_last_name` string, nullable
    - `contact_email` string, nullable
    - `contact_phone` string, nullable
    - `assigned_to_account_id` string, uuid, nullable: The member the event is assigned to (`user_id` of `GET /team-members`).
    - `assigned_to_name` string, nullable
    - `source` string, nullable: Origin of the request, e.g. `platform:Kactus`, `email`, `api`.
    - `tags` string[], nullable
    - `archived_at` string, date-time, nullable: Set when the event is archived (read-only).
    - `stage_id` string, uuid, nullable: Custom stage of the workspace pipeline, under `status`.
    - `stage_name` string, nullable
    - `event_group_id` string, uuid, nullable: Groups sibling events (alternative venue options for one client request).
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
  - `pagination` object, required
    - `page` integer, required: Current 1-based page.
    - `per_page` integer, required: Items per page.
    - `total` integer, nullable, required: Total matching items across all pages (`null` only on a page past the last one, when unknown).
    - `total_pages` integer, nullable, required

## Other responses

- `400`: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
- `401`: Missing, invalid, expired or revoked bearer token (`unauthorized`).
- `429`: Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.

---

[API](https://skmtc.dev/joinways/apis/joinways-public-api.md) · [All operations](https://skmtc.dev/joinways/apis/joinways-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/joinways/apis/joinways-public-api/revisions/39e84309953e?raw)