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

# 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 directory | `GET /v2/traders` | `list_trader_directory` | `directory.read` | Resolve permitted identities, including message-only traders. |
| Trader activity | `GET /v2/traders/activity` | `list_trader_activity` | `stats.read` | Select traders by eligible position count, asset, platform, and position-open time. |
| Legacy trader discovery | `GET /v1/traders` | `list_traders` | `directory.read` | Existing trading-filtered contract, retained during migration. |
| Asset discovery | `GET /v2/assets` | `list_assets` | `directory.read` | Discover assets by name, symbol, or asset class before hydrating stats. |
| Partner feed | `GET /v2/feed` | `list_feed` | `feed.read` | Presentation-ready source-message groups with server-curated events and change polling. |
| Events | `GET /v2/events` | `list_events` | `events.read` | Historical trade-event feed with compact trader, asset, position, and source message IDs. |
| Messages | `GET /v2/messages` | `list_messages` | `messages.read` | Source-message feed with source-platform filtering and direct opaque Source Message ID hydration. |
| Channel summaries | `GET /v2/channel-summaries` | `list_channel_summaries` | `summaries.read` | Compact generated channel narrative summaries. |
| Aggregate summaries | `GET /v2/aggregate-summaries` | `list_aggregate_summaries` | `summaries.read` | Cross-source generated aggregate narrative summaries with coverage counts. |
| Positions | `GET /v2/positions` | `list_positions` | `positions.read` | Open and closed positions by open time with `1D`, `7D`, and `30D` time-based performance. |
| Open positions | `GET /v2/positions/open` | `list_open_positions` | `positions.read` | Currently open positions with current marks and live mark-to-market returns. |
| Trader stats | `GET /v2/traders/stats` | `list_trader_stats` | `stats.read` | Batch source-aware time-based performance and positioning metrics for up to 200 traders. |
| Asset stats | `GET /v2/assets/stats` | `list_asset_stats` | `stats.read` | Batch aggregate positioning and top-trader IDs for up to 200 assets. |
| Trader rankings | `GET /v2/traders/rankings` | `rank_traders` | `stats.read` | Server-side trader ranking by activity or performance without supplying trader IDs. |
| Activity summaries | `GET /v2/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 identity lookup

```bash theme={null}
curl -s 'https://api.centaur.io/v2/traders?search=greekslivenews2&limit=10' \
  -H "x-api-key: $CENTAUR_API_KEY"
```

The directory returns `id`, `name`, `slug`, `avatarUrl`, and a singular nullable `source`. Search matches trader names/slugs and assigned source names, handles, or profile URLs. A trader can appear without messages, positions, or an assigned source. Either message or signal visibility must permit the caller. Directory access does not grant content access.

## Example: select traders by position count

```bash theme={null}
curl -s 'https://api.centaur.io/v2/traders/activity?sourcePlatforms=X&minPositionCount=5&startTime=2026-03-01T00:00:00.000Z&endTime=2026-03-31T23:59:59.999Z&limit=10' \
  -H "x-api-key: $CENTAUR_API_KEY"
```

Activity rows contain `traderId` and `positionCount`. This read requires `stats.read` and signal visibility. Counts exclude deleted positions and assets without an active market. Optional bounds apply inclusively to position open time; omitted bounds are unbounded. `minPositionCount` defaults to `3`; `0` includes zero-position traders, although an asset filter still requires a matching eligible position. Results are alphabetical and paginated. Resolve IDs through the directory when names are needed. Use trader stats for performance metrics.

`GET /v1/traders` and `list_traders` retain their existing contract. See [Trader directory migration](/guides/rest/trader-directory-migration).

## Example: asset discovery

```bash theme={null}
curl -s 'https://api.centaur.io/v2/assets?search=bitcoin&limit=10' \
  -H 'x-api-key: <api-key>'
```

Asset discovery accepts an optional `assetClass` filter on both REST versions and MCP `list_assets`.
Supported values are `crypto`, `stocks`, `indices`, `commodities`, and `fx`.
Multiple values match any selected class and intersect with `search`, `assetIds`, and `traderIds`.

```text theme={null}
GET /v2/assets?assetClass=stocks,indices&limit=10
```

For MCP, pass an array such as `{"assetClass":["stocks","indices"],"limit":10}`.
REST and MCP also accept comma-separated strings. Omit the filter or pass an empty value for all classes, including `other`.
`all`, `equities`, and `other` are not filter values. Invalid values cause a validation error.
Keep the same filters when requesting the next cursor page.

Each discovery result includes two class fields:

* `assetClass` is the raw class: `crypto`, `equities`, `commodities`, `fx`, or `other`.
* `resolvedAssetClass` splits equities into `stocks` and `indices`, matching the web app's market filters.

An equity with an Indices category resolves to `indices`; other equities resolve to `stocks`.
Unknown or missing classes return `other` in both fields.
Assets still need an active market to appear in discovery results.

## Example: messages

```bash theme={null}
curl -s 'https://api.centaur.io/v2/messages?sourcePlatforms=X&startTime=2026-03-01T00:00:00.000Z&limit=10' \
  -H 'x-api-key: <api-key>'
```

`GET /v2/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. Each message returns `traderId`. Pass `traderIds` to select messages from the assigned source of those traders, independently of signal visibility. Resolve names and handles through the trader directory first; message access still requires `messages.read` and message visibility.

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://api.centaur.io/v2/feed?traderIds=412&limit=20' \
  -H 'x-api-key: <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](/guides/rest/feed) for polling and curation rules.

## Example: channel summaries

```bash theme={null}
curl -s 'https://api.centaur.io/v2/channel-summaries?startTime=2026-03-01T00:00:00.000Z&limit=10' \
  -H 'x-api-key: <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://api.centaur.io/v2/aggregate-summaries?startTime=2026-03-01T00:00:00.000Z&limit=10' \
  -H 'x-api-key: <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://api.centaur.io/v2/positions?assetIds=34&limit=10' \
  -H 'x-api-key: <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 /v2/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](/guides/rest/events) and [Trade Classification](/methodology/trade-classification).

## Example: trader stats

```bash theme={null}
curl -s 'https://api.centaur.io/v2/traders/stats?traderIds=17,42&startTime=2026-03-01T00:00:00.000Z&endTime=2026-03-31T23:59:59.999Z' \
  -H 'x-api-key: <api-key>'
```

Trader stats include `summary.timeBasedPerformances` for `1D`, `7D`, and `30D`. Each window reports sampled and scored position counts plus their ratio under `coverage`. 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://api.centaur.io/v2/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: <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`. An omitted sample defaults to UTC year-to-date. Omitted bounds are defaulted independently, so an explicit bound is never changed. 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 `30D`) and require at least `minPositions` scored positions (defaults to 3; pass `minPositions=0` to include all traders). Every performance-ranked row includes `timeBasedPerformance.coverage` with sampled and scored position counts plus their ratio. No additional coverage percentage threshold is applied.

A position opened at time T is evaluated at T plus the evaluation window. If no position in the resolved sample can have reached that window, the API returns `422` (`PERFORMANCE_WINDOW_NOT_ELAPSED`). The error includes the requested and resolved values plus valid retry alternatives. The API does not change the requested windows or retry automatically.

## Example: activity summaries

```bash theme={null}
curl -s 'https://api.centaur.io/v2/activity-summaries?groupBy=trader&interval=day&limit=10' \
  -H 'x-api-key: <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](/guides/rest/overview)
* [Partner Feed guide](/guides/rest/feed)
* [Events usage guide](/guides/rest/events)
* [Contract limits](/guides/agent-client-contract-limits)
* [API reference overview](/api-reference/overview)