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

# List events grouped by date

`GET /events`

Retrieve events grouped by date with limited events per day.

**Pagination model:** `limit` and `offset` paginate across the total event pool (i.e. across all days in the requested range). `events_per_day` then caps how many events are shown inside each day bucket. `meta.total_items` reflects the total number of matching events (not days). `remaining_count` on each day group indicates how many additional events exist beyond `events_per_day` for that day.

Existing response keys (`date`, `events`, `remaining_count`) are unchanged.

## Query parameters

- `events_per_day` integer — Maximum number of events to show per day
- `limit` integer — Maximum total number of events to include across all day groups. Controls how many events are fetched before grouping by date.
- `offset` integer — Number of events to skip before applying the day grouping.
- `start_date` string, date, nullable — Start date for event range (YYYY-MM-DD)
- `end_date` string, date, nullable — End date for event range (YYYY-MM-DD)

## Response `200`

Successfully retrieved events grouped by date

- object
  - `ok` boolean, required
  - `data` object[]
    - `date` string, date
    - `events` object[]
      - `id` string, uuid
      - `client_full_name` string
      - `client_email` string, email
      - `client_phone_number` string
      - `status` string
      - `details` string
      - `starting_date` string, date-time
      - `ending_date` string, date-time
      - `created_at` string, date-time
    - `remaining_count` integer
  - `meta` object
    - `limit` integer
    - `offset` integer
    - `total_items` integer

## Other responses

- `401` — Invalid or missing API key
- `403` — Insufficient permissions

---

[API](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1.md) · [All operations](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yourang/yourang-ai-external-api-v1/versions/49680ee64400/schema)