> ## 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. # Available Data Reads > Pick the right REST endpoint or MCP tool for the partner feed, events, messages, summaries, positions, discovery, and stats. Use this page to choose the right Centaur read surface without scanning the full generated reference first. ## Capability map | Data family | REST endpoint | MCP tool | Required scope | Notes | | ------------------- | --------------------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- | | Trader discovery | `GET /api/v1/traders` | `list_traders` | `directory.read` | Discover traders by name, source platform, or related asset filters before hydrating stats. | | Asset discovery | `GET /api/v1/assets` | `list_assets` | `directory.read` | Discover assets directly by name or symbol before hydrating stats. | | Partner feed | `GET /api/v1/feed` | `list_feed` | `feed.read` | Presentation-ready source-message groups with server-curated events and change polling. | | Events | `GET /api/v1/events` | `list_events` | `events.read` | Historical trade-event feed with compact trader, asset, position, and source message IDs. | | Messages | `GET /api/v1/messages` | `list_messages` | `messages.read` | Source-message feed with source-platform filtering and direct opaque Source Message ID hydration. | | Channel summaries | `GET /api/v1/channel-summaries` | `list_channel_summaries` | `summaries.read` | Compact generated channel narrative summaries. | | Aggregate summaries | `GET /api/v1/aggregate-summaries` | `list_aggregate_summaries` | `summaries.read` | Cross-source generated aggregate narrative summaries with coverage counts. | | Positions | `GET /api/v1/positions` | `list_positions` | `positions.read` | Open and closed positions by open time with `1D`, `7D`, and `30D` time-based performance. | | Open positions | `GET /api/v1/positions/open` | `list_open_positions` | `positions.read` | Currently open positions with current marks and live mark-to-market returns. | | Trader stats | `GET /api/v1/traders/stats` | `list_trader_stats` | `stats.read` | Batch source-aware time-based performance and positioning metrics for up to 200 traders. | | Asset stats | `GET /api/v1/assets/stats` | `list_asset_stats` | `stats.read` | Batch aggregate positioning and top-trader IDs for up to 200 assets. | | Trader rankings | `GET /api/v1/traders/rankings` | `rank_traders` | `stats.read` | Server-side trader ranking by activity or performance without supplying trader IDs. | | Activity summaries | `GET /api/v1/activity-summaries` | `summarize_message_activity` | `stats.read` | Deterministic message and event counts per trader or overall, bucketed by hour, day, or week. | ## Observable behavior across reads * Operations are scope-gated. A key may work on some endpoint families and return `403` on others. * Historical list reads and stats responses echo the applied bounds back to you after server-side clamping. * Some rows may be omitted because they are deleted, tied to ineligible connected entities, or outside the current access policy. Omitted rows do not produce placeholder warnings. * Cursor pagination always reflects the current eligible result set, not a frozen snapshot. * 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-position reads expose best-effort current marks when pricing is available. They do not currently expose a separate `priceAsOf` field. ## Example: trader discovery ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/traders?search=runner&sourcePlatforms=X&minTrades=5&startTime=2026-03-01T00:00:00.000Z&endTime=2026-03-31T23:59:59.999Z&limit=10' \ -H 'x-api-key: ' ``` Trader discovery rows include `tradeCount` plus one nested `source` identity for the trader's source platform, with platform, handle, display name, profile URL, avatar URL, and follower/subscriber count when available. Use `sourcePlatforms=TELEGRAM`, `sourcePlatforms=X`, or a comma-separated list to filter discovery before calling stats or detail reads. Use `minTrades` to require a minimum eligible visible position count; it defaults to `3`, and `minTrades=0` returns the full visible directory. `startTime` and `endTime` scope discovery `tradeCount` and `minTrades` by position open time. Trader stats rows expose the same `source` shape and accept the same `sourcePlatforms` filter. ## Example: asset discovery ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/assets?search=bitcoin&limit=10' \ -H 'x-api-key: ' ``` ## Example: messages ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/messages?sourcePlatforms=X&startTime=2026-03-01T00:00:00.000Z&limit=10' \ -H 'x-api-key: ' ``` `GET /api/v1/messages` returns eligible source messages as a feed. Pass `sourcePlatforms=TELEGRAM`, `sourcePlatforms=X`, or a comma-separated list to filter by source platform. Pass `ids` to hydrate opaque Source Message IDs returned by message rows or event `messageId` references. Message rows do not expose `traderId`; use event `messageId` references or source-message IDs when you need to connect messages to event rows. Each message row has `id` as the stable Source Message ID and a nested `source` payload. `source.identity` describes the source account or channel, including `platform`, handle, display name, profile URL, avatar URL, and follower/subscriber count when available. `source.preview` contains the message timestamp, original source URL, sanitized text, attachments, and platform-specific flags such as reply, quote, repost, or edit state when available. ## Example: partner feed ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/feed?traderIds=412&limit=20' \ -H 'x-api-key: ' ``` The partner feed groups curated events by Source Message ID and embeds the source, trader, and asset display fields needed for rendering. Use `cursor` for older pages and `since` for ingestion-watermark change polling. A group returned by `since` is a whole-group upsert, so replace the prior group by `id`. See the [Partner Feed guide](/docs/guides/rest/feed) for polling and curation rules. ## Example: channel summaries ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/channel-summaries?startTime=2026-03-01T00:00:00.000Z&limit=10' \ -H 'x-api-key: ' ``` Generated channel narrative summaries are compact by default. They return `traderId`, the source window, overview, market bias, capped key insights, capped mentioned assets, and pagination metadata. The `traderId` lets clients connect summaries from the same trader over time, but this read does not accept trader or Telegram channel filters. The default response includes only substantive `safe` summaries; pass `includeLowSignal=true` to include low-signal windows. This read supports a maximum `limit` of 200. `startTime` and `endTime` select summaries whose Source Windows overlap the requested interval. For daily reads, use UTC day bounds such as `2026-03-01T00:00:00.000Z` through `2026-03-02T00:00:00.000Z`. Channel summaries return a concise narrative shape without trader metadata, channel identity, raw source material, verbose rationales, or generator safety metadata. ## Example: aggregate summaries ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/aggregate-summaries?startTime=2026-03-01T00:00:00.000Z&limit=10' \ -H 'x-api-key: ' ``` Generated aggregate narrative summaries synthesize the Aggregate Window across eligible sources. They return a headline, overview, dominant narratives, contrarian theses, market drivers, asset sentiment, risks, source coverage counts, and pagination metadata. The default response includes only substantive `safe` summaries; pass `includeLowSignal=true` to include low-signal windows. This read supports a maximum `limit` of 200. `startTime` and `endTime` select summaries whose Aggregate Windows overlap the requested interval. Public responses expose coverage counts only, not trader or channel identities. Use generated narrative summaries for questions about highlighted themes, narratives, drivers, asset sentiment, and risks. Use trader rankings for activity and performance rankings, activity summaries for counts and trends, and events, messages, positions, open positions, and stats for other exact trade facts and current positioning. ## Example: positions ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/positions?assetIds=34&limit=10' \ -H 'x-api-key: ' ``` Positions include open and closed rows selected by position open time. Pass `positionIds` to hydrate positions referenced by event rows. Each row includes `timeBasedPerformances` for `1D`, `7D`, and `30D` fixed windows after entry. A window value can be `null` when no evaluation exists for that position. When present, its `status` is machine-readable; `ready` rows include `returnPercentage`, while statuses such as `too_young`, `missing_forward_price`, or `calculation_error` explain why the fixed-window return is unavailable. Use `GET /api/v1/positions/open` or `list_open_positions` when you need current marks, live mark-to-market returns, or current open-position skew for currently open positions. ## Event flags Event rows can include `assumed`, `retrospective`, and `autoGenerated` flags. These flags explain how an event entered the position history. Normal user-facing event listings should skip assumed and auto-generated system events unless the user specifically asks about system events, missing closes, or reconstruction behavior. See [Events usage guide](/docs/guides/rest/events) and [Trade Classification](/docs/methodology/trade-classification). ## Example: trader stats ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/traders/stats?traderIds=17,42&startTime=2026-03-01T00:00:00.000Z&endTime=2026-03-31T23:59:59.999Z' \ -H 'x-api-key: ' ``` Trader stats include `summary.timeBasedPerformances` for `1D`, `7D`, and `30D`. Empty aggregates return null metrics with `positionsCount: 0`. Missing or inaccessible IDs are returned in `data.meta.missingTraderIds`. Trader stats rows also include `tags`: editorial trader tags as `{ category, name }` pairs, lowercase. The first category is `thematic`, the macro themes a trader's book expresses (for example `ai capex buildout` or `power and energy`); categories are an open set and may grow over time. `tags` is always present and empty for untagged traders. ## Example: trader rankings ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/traders/rankings?metric=win_rate&startTime=2026-06-01T00:00:00.000Z&endTime=2026-06-25T00:00:00.000Z&limit=10' \ -H 'x-api-key: ' ``` Trader rankings answer "most active" and "best performing" questions server-side, without requiring trader IDs and without paging raw events. Rank by the activity metrics `event_count` (default) or `position_count`, or by the performance metrics `win_rate`, `avg_return`, `median_return`, or `sharpe_ratio`. The window defaults to the last 7 days; pass explicit UTC `startTime`/`endTime` for other windows. Results are bounded (`limit` defaults to 10, maximum 50) with `meta.totalCandidates` reporting how many traders qualified. Performance metrics evaluate positions at the `timeBasedPerformanceWindow` (defaults to `7D`) and require at least `minPositions` evaluated positions (defaults to 3; pass `minPositions=0` to include all traders). Every performance-ranked row includes `timeBasedPerformance.positionsCount` so thin samples can be qualified. A position opened at time T is evaluated at T plus the evaluation window, so performance rankings require `startTime` to be at least the evaluation window before now. A `30D` ranking over positions opened in the last week is structurally unanswerable. Such requests are rejected with a `422` (`PERFORMANCE_WINDOW_NOT_ELAPSED`) telling you to move `startTime` back or pick a shorter window. ## Example: activity summaries ```bash theme={null} curl -s 'https://partners.centaur.io/api/v1/activity-summaries?groupBy=trader&interval=day&limit=10' \ -H 'x-api-key: ' ``` Activity summaries return deterministic message and event counts, valid evidence for counts, volumes, and trends. They group by `trader` (default) or overall with `groupBy=none`, and bucket by `hour`, `day` (default), or `week`. They are not generated narrative summaries. Each group returns totals plus per-bucket `messageCount` and `eventCount`; buckets with no activity are omitted. `meta.totalMessages` and `meta.totalEvents` cover all groups, not only the returned top groups. The window defaults to the last 7 days. Requests are rejected with `422` when the window/interval combination would produce more than 168 buckets per group. Widen the interval or narrow the window. Use `eventTypes` to restrict event counts and `traderIds` to scope groups. ## Next steps * [REST overview](/docs/guides/rest/overview) * [Partner Feed guide](/docs/guides/rest/feed) * [Events usage guide](/docs/guides/rest/events) * [Contract limits](/docs/guides/agent-client-contract-limits) * [API reference overview](/docs/api-reference/overview)