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

# Events Usage Guide

> Filter, sort, and paginate the public events feed.

`GET /api/v1/events` returns a paginated list of public trading events.

## Supported filters

* `traderIds`
* `assetIds`
* `directions`
* `types`
* `startTime`
* `endTime`
* `limit`
* `cursor`

## Example: filter by asset

```bash theme={null}
curl -s 'https://partners.centaur.io/api/v1/events?assetIds=34&limit=10' \
  -H 'x-api-key: <api-key>'
```

## Example: time-bounded query

```bash theme={null}
curl -s 'https://partners.centaur.io/api/v1/events?startTime=2026-03-01T00:00:00.000Z&endTime=2026-03-31T23:59:59.999Z&limit=25' \
  -H 'x-api-key: <api-key>'
```

## Default time range

* If `startTime` and `endTime` are both omitted, the API may apply a bounded default window.
* If an explicit `startTime` is earlier than the accessible window, the API can clamp it forward.
* The actual bounds used for the response are returned in `data.meta.appliedTimeRange`.

## Pagination rules

* Pass `cursor` from `meta.nextCursor` to advance to the next page.
* Pagination is forward-only.
* Cursors remain usable if matching events disappear between requests because of deletion or eligibility changes.
* Later pages may omit rows that disappeared after an earlier fetch.
* Pagination reflects the current eligible set and is not a frozen snapshot.
* `limit` accepts up to `200`.

## Event classification flags

Event rows include three boolean classification flags:

| Flag            | Meaning                                                                              | Default presentation                                                                |
| --------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `assumed`       | The system inferred the event from position progression.                             | Hide in normal listings unless the user asks about inferred events or gaps.         |
| `retrospective` | The source described the action after it happened.                                   | Mention only when timing matters.                                                   |
| `autoGenerated` | The system generated the event, usually to close stale or superseded position state. | Hide in normal listings unless the user asks about system events or missing closes. |

Agents and product clients should not present `assumed=false` or `autoGenerated=false` as meaningful user-facing attributes. The absence of a flag is the normal case.

## Hydrating context

Event rows expose compact references:

* `positionId` for the related position
* `messageId` for the related Source Message ID when available
* `traderId` and `assetId` for discovery hydration

Use `GET /api/v1/positions?positionIds=...` for position performance and `GET /api/v1/messages?ids=...` for source-message text or attachments.

## Related pages

* [Query semantics](/docs/api-reference/conventions/query-semantics)
* [Request and response envelopes](/docs/api-reference/conventions/request-response-envelopes)
* [Trade classification](/docs/methodology/trade-classification)
* [MCP overview](/docs/guides/mcp-agents/overview)