> ## 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.

# Query Semantics

> Filter rules, cursor behavior, and applied time-range behavior across the full Centaur read surface.

## Multi-value filters

* Endpoint-specific filters differ by read family. Use the generated API reference for the exact parameter set on each endpoint or tool.
* Multi-value filters such as `traderIds`, `assetIds`, `directions`, event `types`, and message `ids` can be passed as comma-separated values in REST.

## Historical list reads

Events, messages, the partner feed, positions, channel summaries, and aggregate summaries use:

* `startTime`
* `endTime`
* `limit`
* `cursor`

The partner feed also accepts `since` for ingestion-watermark change polling. `cursor` and `since` are mutually exclusive, and feed `limit` counts source-message groups with a maximum of `100`.

Historical list responses echo the actual bounds used by the server in `meta.appliedTimeRange`.

Position `startTime` and `endTime` bounds select positions by open time.

Channel summary `startTime` and `endTime` bounds select Source Windows that overlap the requested interval. A Source Window is included when `windowEnd` is after `startTime` and `windowStart` is before `endTime`.

Aggregate summary `startTime` and `endTime` bounds use the same overlap rule against Aggregate Windows.

Generated narrative summaries describe market narratives for their Source Window or Aggregate Window. They are not evidence for exact trade counts, public activity rankings, or current open-position skew.

## Open positions

Open positions are paginated with:

* `limit`
* `cursor`

Open positions do not use `startTime` or `endTime`.

Use open-position reads for current positioning and open-position skew claims.

## Stats reads

Trader stats require `traderIds`; asset stats require `assetIds`. Each request accepts up to 200 IDs and preserves the requested order for returned results.

Trader and asset stats accept explicit `startTime` and `endTime` filters.

Stats responses echo the applied bounds in `filtersApplied.appliedTimeRange`.
Missing or inaccessible IDs are reported in `meta.missingTraderIds` or `meta.missingAssetIds`.

## Cursor rules

* Pagination is forward-only.
* `meta.nextCursor` advances forward.
* Cursors remain usable if matching events disappear between requests.
* Disappeared rows may be absent from later pages.
* Pagination reflects the current eligible set and is not a frozen snapshot.
* `limit` accepts up to `200` on list reads.

The partner feed is the exception to the general cursor limit and continuation rule: its maximum is `100`, and a non-empty response can retain `nextCursor` when `hasMore` is `false` so that token can become the next `since` watermark. When a `since` response has `hasMore: true`, pass `nextCursor` as `since` to continue the same change batch.

## Partner feed change polling

The partner feed's `since` mode is an ingestion-watermark change feed, not message-time pagination. A newly ingested retrospective event can therefore make an older message group reappear. Each returned group is a whole-group upsert: merge by group `id` and replace the complete prior payload.

`cursor` and `since` are mutually exclusive. Continue a multi-page change batch with `since`, and persist the newest non-null `nextCursor` after every successful poll, including empty polls, so the ingestion watermark advances through quiet periods. See [Partner Feed](/docs/guides/rest/feed) for the overlap guidance needed around concurrent commits.

## Result ordering

Ordering is fixed per read family. There is no sort parameter.

* Events, messages, the partner feed, positions, open positions, channel summaries, and aggregate summaries return newest rows first. Feed groups use source-message post time descending with Source Message ID as the tiebreak; events inside each feed group use event time descending with event ID as the tiebreak.
* Trader and asset discovery return rows alphabetically: case-insensitive name ascending with `id` as the tiebreak.
* Trader rankings return rows ordered by the requested metric descending, not by timestamp.
* Activity summaries return buckets ascending by bucket start within each group.

## Time rules

* Historical list reads may default to a bounded time window when `startTime` and `endTime` are omitted.
* Stats reads cover the full accessible history unless explicit bounds are provided.
* If an explicit `startTime` falls outside the accessible range, the server can clamp it forward.

## Filtering and suppression

* Some rows may be omitted because they are deleted, tied to ineligible connected entities, or outside the current access policy.
* Suppressed rows are omitted silently rather than returned with placeholder warnings.
* Trader discovery supports `minTrades`, defaulting to `3`, to suppress traders below a minimum eligible visible position count. Pass `minTrades=0` when a client needs the full visible trader directory. Trader discovery `startTime` and `endTime` scope `tradeCount` and `minTrades` by position open time; performance metrics stay on stats reads.
* Messages are a feed by default. `ids`, `sourcePlatforms`, `startTime`, and `endTime` apply to the message feed itself.
* Messages do not support trader, asset, direction, or event-type filters.
* The partner feed supports trader and asset filters, but curation removes assumed and GC-generated closes, instant opens, and siblinged assumed opens before message grouping. Lone inferred opens, assumed increases, assumed decreases, and retrospective events remain visible; Centaur may also exclude specific sources from this curated feed for editorial or quality reasons without removing them from raw reads.

## Client contract limits

Some workflows require multiple reads or explicit qualification. Centaur does not expose a single global trader-ranking endpoint, a `3D` performance window, trader filters on messages, or a public close-return performance mode. See [Agent and Client Contract Limits](/docs/guides/agent-client-contract-limits).

## Surface parity

REST query params and MCP tool arguments intentionally match each other closely.