> ## 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. # Rank traders > Ranks traders across the platform by activity or performance over an explicit UTC time window, without requiring trader IDs. Returns a small bounded result ordered by the applied metric. Use this instead of paging raw events or messages for "most active" or "best performing" questions. ## OpenAPI ````yaml /openapi.json get /api/v1/traders/rankings openapi: 3.1.0 info: title: Centaur API version: 1.0.0 description: >- Public, read-only API for Centaur's data over REST with a companion MCP surface. servers: - url: https://partners.centaur.io description: Current service base URL security: [] tags: - name: System description: Health and service metadata endpoints. - name: Discovery description: Read-only trader and asset directory discovery endpoints. - name: Events description: >- Historical trade-event reads with source, trader, asset, and position context. - name: Messages description: >- Read-only access to source messages by message timestamp or Source Message ID. - name: Channel Summaries description: Generated channel narrative summaries selected by Source Window overlap. - name: Aggregate Summaries description: >- Generated aggregate narrative summaries selected by Aggregate Window overlap. - name: Positions description: Read-only position history and open-position live state reads. - name: Stats description: Read-only aggregate trader and asset stats. externalDocs: description: Canonical Centaur API documentation url: https://partners.centaur.io/docs paths: /api/v1/traders/rankings: get: tags: - Rankings summary: Rank traders description: >- Ranks traders across the platform by activity or performance over an explicit UTC time window, without requiring trader IDs. Returns a small bounded result ordered by the applied metric. Use this instead of paging raw events or messages for "most active" or "best performing" questions. operationId: listTraderRankings parameters: - schema: allOf: - $ref: '#/components/schemas/TraderRankingMetric' - description: >- Ranking metric. Activity metrics: `event_count` (default) and `position_count`. Performance metrics: `win_rate`, `avg_return`, `median_return`, and `sharpe_ratio`. required: false description: >- Ranking metric. Activity metrics: `event_count` (default) and `position_count`. Performance metrics: `win_rate`, `avg_return`, `median_return`, and `sharpe_ratio`. name: metric in: query - schema: anyOf: - type: string - type: array items: type: string - type: array items: type: number description: Restrict the ranking to traders active in specific asset IDs. required: false description: Restrict the ranking to traders active in specific asset IDs. name: assetIds in: query - schema: allOf: - $ref: '#/components/schemas/TraderDirection' - description: 'Filter to a single direction: `long` or `short`.' required: false description: 'Filter to a single direction: `long` or `short`.' name: direction in: query - schema: allOf: - $ref: '#/components/schemas/TimeBasedPerformanceWindow' - description: >- Time-based performance evaluation window for performance metrics. Defaults to `7D`. Ignored for activity metrics. Positions are evaluated this long after they open, so `startTime` must be at least this far in the past or the request is rejected. required: false description: >- Time-based performance evaluation window for performance metrics. Defaults to `7D`. Ignored for activity metrics. Positions are evaluated this long after they open, so `startTime` must be at least this far in the past or the request is rejected. name: timeBasedPerformanceWindow in: query - schema: type: integer nullable: true minimum: 0 description: >- Minimum evaluated positions required for performance-metric rankings. Defaults to 3; pass 0 to include all traders. Ignored for activity metrics. required: false description: >- Minimum evaluated positions required for performance-metric rankings. Defaults to 3; pass 0 to include all traders. Ignored for activity metrics. name: minPositions in: query - schema: type: string format: date-time description: >- Inclusive ISO-8601 lower time bound on position open time. Defaults to 7 days before the applied endTime. For performance metrics it must be at least the evaluation window before now. required: false description: >- Inclusive ISO-8601 lower time bound on position open time. Defaults to 7 days before the applied endTime. For performance metrics it must be at least the evaluation window before now. name: startTime in: query - schema: type: string format: date-time description: >- Inclusive ISO-8601 upper time bound. Defaults to the current server time. required: false description: >- Inclusive ISO-8601 upper time bound. Defaults to the current server time. name: endTime in: query - schema: type: integer minimum: 1 maximum: 50 description: >- Maximum number of ranked traders to return. Defaults to 10, maximum 50. required: false description: >- Maximum number of ranked traders to return. Defaults to 10, maximum 50. name: limit in: query responses: '200': description: Bounded trader ranking for the applied metric and time window content: application/json: schema: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/TraderRankingsResponseData' requestId: type: string example: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 required: - success - data - requestId '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: UNAUTHORIZED message: Unauthorized requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: FORBIDDEN message: Forbidden requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 '422': description: >- Validation error, including performance-metric windows whose startTime is too recent for the evaluation window to have elapsed content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: PERFORMANCE_WINDOW_NOT_ELAPSED message: >- No position opened in the applied time range can have a completed 30D time-based evaluation yet. Set startTime to at least 30 days before now, or use a shorter timeBasedPerformanceWindow. requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 '503': description: Authentication service temporarily unavailable headers: Retry-After: description: Seconds to wait before retrying authentication schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: AUTHENTICATION_UNAVAILABLE message: Authentication is temporarily unavailable requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 security: - ApiKeyAuth: [] components: schemas: TraderRankingMetric: type: string enum: - event_count - position_count - win_rate - avg_return - median_return - sharpe_ratio TraderDirection: type: string enum: - long - short TimeBasedPerformanceWindow: type: string enum: - 1D - 7D - 30D TraderRankingsResponseData: type: object properties: filtersApplied: type: object properties: metric: $ref: '#/components/schemas/TraderRankingMetric' assetIds: type: array items: type: integer direction: allOf: - $ref: '#/components/schemas/TraderDirection' - nullable: true timeBasedPerformanceWindow: allOf: - $ref: '#/components/schemas/TimeBasedPerformanceWindow' - nullable: true minPositions: type: integer nullable: true appliedTimeRange: $ref: '#/components/schemas/AppliedTimeRange' required: - metric - assetIds - direction - timeBasedPerformanceWindow - minPositions - appliedTimeRange results: type: array items: $ref: '#/components/schemas/TraderRanking' meta: type: object properties: totalCandidates: type: integer description: >- Number of traders that qualified for the ranking before the limit was applied. required: - totalCandidates required: - filtersApplied - results - meta ErrorEnvelope: type: object properties: success: type: boolean enum: - false error: $ref: '#/components/schemas/Error' requestId: type: string example: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 required: - success - error - requestId AppliedTimeRange: type: object properties: startTime: type: string nullable: true format: date-time endTime: type: string nullable: true format: date-time required: - startTime - endTime TraderRanking: type: object properties: traderId: type: integer description: Related trader ID. Use trader discovery for display metadata. rank: type: integer description: 1-based rank position for the applied metric. metricValue: type: number nullable: true description: Value of the applied ranking metric for this trader. eventCount: type: integer description: Events for this trader inside the applied time range. positionCount: type: integer description: Positions opened by this trader inside the applied time range. directionBias: $ref: '#/components/schemas/DirectionBias' timeBasedPerformance: $ref: '#/components/schemas/TraderRankingTimeBasedPerformance' required: - traderId - rank - metricValue - eventCount - positionCount - directionBias - timeBasedPerformance Error: type: object properties: code: type: string description: Stable machine-readable error code. example: UNAUTHORIZED message: type: string description: Human-readable explanation for the failure. example: Unauthorized details: nullable: true description: Optional structured details for validation or input failures. required: - code - message DirectionBias: type: object properties: label: type: string enum: - long - short - neutral longCount: type: integer shortCount: type: integer longPercentage: type: number nullable: true shortPercentage: type: number nullable: true required: - label - longCount - shortCount - longPercentage - shortPercentage TraderRankingTimeBasedPerformance: type: object nullable: true properties: window: $ref: '#/components/schemas/TimeBasedPerformanceWindow' averageReturnPercentage: type: number nullable: true medianReturnPercentage: type: number nullable: true winRatePercentage: type: number nullable: true sharpeRatio: type: number nullable: true positionsCount: type: integer description: >- Number of evaluated positions in the applied window. Qualify thin samples when presenting results. required: - window - averageReturnPercentage - medianReturnPercentage - winRatePercentage - sharpeRatio - positionsCount description: >- Time-based performance summary for the applied window. Present for performance metrics, null for activity metrics. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Centaur. x-default: ````