Query Semantics

​

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

​

Surface parity

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