> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centaur.io/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 /v2/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://api.centaur.io/v2/events?assetIds=34&limit=10' \
  -H 'x-api-key: <api-key>'
```

## Example: time-bounded query

```bash theme={null}
curl -s 'https://api.centaur.io/v2/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`.
* The server's current UTC time is returned in `data.meta.serverTime`. Use it to resolve phrases like "today" or "last 7 days" into explicit bounds for the next request.

## 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 /v2/positions?positionIds=...` for position performance and `GET /v2/messages?ids=...` for source-message text or attachments.

## Related pages

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