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

# Events API

> Lead/sale event stream listing with date filters, sorting, and paginated responses

# Events API

`/events` exposes event-level lead and sale rows for troubleshooting conversion pipelines and customer journeys.

## Endpoint

| Method | Path      | Purpose                                  |
| ------ | --------- | ---------------------------------------- |
| `GET`  | `/events` | List lead/sale events in workspace scope |

## Query parameters

| Param        | Type            | Notes                                                                                                 |
| ------------ | --------------- | ----------------------------------------------------------------------------------------------------- |
| `type`       | `lead \| sale`  | Optional filter. Any other value returns `400`.                                                       |
| `linkId`     | `string`        | Optional link-level filter.                                                                           |
| `customerId` | `string`        | Optional customer filter.                                                                             |
| `start`      | `date/datetime` | Optional start bound. Date-only values are normalized to `00:00:00`.                                  |
| `end`        | `date/datetime` | Optional end bound. Date-only values are normalized to `23:59:59`.                                    |
| `page`       | `number`        | Default `1`.                                                                                          |
| `limit`      | `number`        | Default `50`, max `100`.                                                                              |
| `sortBy`     | `string`        | Allowed: `timestamp`, `event_type`, `event_name`, `amount_in_usd`, `country`, `customer_external_id`. |
| `sortOrder`  | `asc \| desc`   | Optional sort direction.                                                                              |

## Response shape

* `data`: array of event rows
* `meta.page`: current page
* `meta.limit`: page size
* `meta.hasMore`: pagination hint for next-page loading

## Permissions and availability

* Requires workspace auth.
* Requires `links:read` permission.
* If analytics backend is unavailable, endpoint returns `503`.

## Caching behavior

Read responses are snapshot-cached for short TTL windows to reduce repeated analytics fetches while preserving near-real-time usability.

## Typical failures

* `400 BAD_REQUEST`: invalid `type`
* `503 SERVICE_UNAVAILABLE`: analytics service not configured
* `500 ANALYTICS_ERROR`: upstream analytics query failure

Related docs:

* `/user-guides/manual/data/events-and-customers-operations-reference`
* `/user-guides/manual/data/exports-and-operational-checks`
* `/user-guides/manual/data/analytics-and-reporting`