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

# List appointments

`GET /v1/appointments`

Returns cursor-paginated appointments backed by the Conduit booking service. v1 exposes allocation + `external_id` context only; full appointment details (scheduled time, assigned agent, location) are retrievable from the booking service using `external_id`.

## Query parameters

- `workspace_id` string, required — Workspace to query.
- `limit` integer — Page size. Defaults to 20. Max 100.
- `cursor` string — Pagination cursor returned as `next_cursor` on the previous page.
- `order` 'asc' | 'desc' — Sort direction over scheduled start time. Defaults to `desc` (most recently scheduled first).
- `status` 'awaiting_response' | 'awaiting_confirmation' | 'confirmed' | 'cancelled' | 'completed' | 'no_show' | 'rescheduled' — Filter by appointment status. Use `completed`, `no_show`, `cancelled`, or `rescheduled` to compute booking efficacy rates.
- `start_after` string, date-time — Only return appointments scheduled at or after this ISO 8601 timestamp.
- `start_before` string, date-time — Only return appointments scheduled strictly before this ISO 8601 timestamp.

## Response `200`

Appointments

- object — Cursor-paginated appointments response.
  - `data` object[], required
    - `id` string, required — Conduit appointment id.
    - `workspace_id` string, required
    - `contact_id` string, nullable, required — Contact associated with this appointment. `null` if the appointment is not yet linked to a contact.
    - `external_id` string, nullable, required — Upstream booking service id (typically prefixed `bk_`). `null` if the appointment was created outside the booking service sync.
    - `status` 'awaiting_response' | 'awaiting_confirmation' | 'confirmed' | 'cancelled' | 'completed' | 'no_show' | 'rescheduled', required — Appointment lifecycle status. Use `completed`, `no_show`, `cancelled`, and `rescheduled` to compute booking efficacy rates.
    - `start_at` string, nullable, required — ISO 8601 scheduled start time. `null` if the appointment is a scheduling link that has not been claimed.
    - `end_at` string, nullable, required — ISO 8601 scheduled end time.
    - `duration_ms` number, nullable, required — Scheduled duration in milliseconds, derived from `end_at - start_at`. `null` if either boundary is missing.
    - `origin` string, nullable, required — Where the booking originated (e.g. `call`, `text`, `direct`).
    - `notes` string, nullable, required — Operator-entered notes about the appointment.
    - `generated_context` string, nullable, required — AI-generated summary of the conversation context leading to the booking.
    - `short_link_id` string, required — Identifier of the scheduling short link used to create this appointment.
    - `strength_indicator` number, nullable, required — Optional 0..1 confidence score of booking quality (provided by the booking service).
    - `booking_info` object, required — Contact details captured at the time of booking.
      - `name` string, nullable, required
      - `email` string, nullable, required
      - `phone` string, nullable, required
      - `notes` string, nullable, required
    - `references` object[], required — External entities the appointment is scoped to (e.g. a property or unit).
      - `id` string, nullable, required
      - `type` 'property' | 'unit' | 'unknown', required
      - `value` string, required
    - `last_synced_at` string, nullable, required — ISO 8601 of the last sync from the upstream booking service.
    - `created_at` string, required
  - `next_cursor` string, nullable, required
  - `has_more` boolean, required

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/conduit/apis/conduit-api.md) · [All operations](https://skmtc.dev/conduit/apis/conduit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/conduit/conduit-api/revisions/3ad7e17f96ad/schema)