> ## Documentation Index
> Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Falcon Leaderboard

> Rank Polymarket traders using the Falcon F-Score, a composite metric for consistent high-quality performance.

**Platform:** Polymarket\
**Endpoint:** `POST /v2/semantic/retrieve/parameterized`\
**Authentication:** Bearer token

## Query parameters

All requests use `agent_id` `584` (Falcon Leaderboard). Set filters inside `params` in the playground — all values must be strings.

| Parameter | Type | Description |
| - | - | - |
| `min_win_rate_15d` | String | Minimum 15-day win rate (0–1). |
| `max_win_rate_15d` | String | Maximum 15-day win rate (0–1). |
| `min_roi_15d` | String | Minimum 15-day ROI. |
| `min_total_trades_15d` | String | Minimum trades in the last 15 days. |
| `max_total_trades_15d` | String | Maximum trades in the last 15 days. |
| `min_pnl_15d` | String | Minimum realized PnL in USD over 15 days. |
| `sort_by` | String | Sort metric: `f_score`, `roi`, `pnl`, `win_rate`, `trades`, or `sharpe`. |

## Example Request

```bash cURL theme={null}
curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 584,
  "params": {
    "min_win_rate_15d": "0.45",
    "max_win_rate_15d": "0.95",
    "min_roi_15d": "0",
    "min_total_trades_15d": "50",
    "max_total_trades_15d": "100000",
    "min_pnl_15d": "5000",
    "sort_by": "roi"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 584,
    "params": {
        "min_win_rate_15d": "0.45",
        "max_win_rate_15d": "0.95",
        "min_roi_15d": "0",
        "min_total_trades_15d": "50",
        "max_total_trades_15d": "100000",
        "min_pnl_15d": "5000",
        "sort_by": "roi"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "agent_id": 584,
  "params": {
    "min_win_rate_15d": "0.45",
    "max_win_rate_15d": "0.95",
    "min_roi_15d": "0",
    "min_total_trades_15d": "50",
    "max_total_trades_15d": "100000",
    "min_pnl_15d": "5000",
    "sort_by": "roi"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();
```


## OpenAPI

````yaml /api-reference/polymarket-falcon-leaderboard.openapi.json POST /api/v2/semantic/retrieve/parameterized
openapi: 3.1.0
info:
  title: Falcon API — Falcon Leaderboard
  version: 1.0.0
servers:
  - url: https://narrative.agent.heisenberg.so
    description: Production
security:
  - bearerAuth: []
paths:
  /api/v2/semantic/retrieve/parameterized:
    post:
      tags:
        - Polymarket
      summary: Falcon Leaderboard
      description: >-
        Rank Polymarket traders using the Falcon F-Score and filter by 15-day
        performance metrics.
      operationId: polymarketFalconLeaderboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolymarketFalconLeaderboardRequest'
            examples:
              default:
                summary: Top traders by ROI with F-Score filters
                value:
                  agent_id: 584
                  params:
                    min_win_rate_15d: '0.45'
                    max_win_rate_15d: '0.95'
                    min_roi_15d: '0'
                    min_total_trades_15d: '50'
                    max_total_trades_15d: '100000'
                    min_pnl_15d: '5000'
                    sort_by: roi
                  pagination:
                    limit: 10
                    offset: 0
                  formatter_config:
                    format_type: raw
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolymarketFalconLeaderboardResponse'
        '400':
          description: Bad request — check params
        '401':
          description: Unauthorized — check your Bearer token
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
              --header 'Authorization: Bearer YOUR_TOKEN' \
              --header 'Content-Type: application/json' \
              --data '{
              "agent_id": 584,
              "params": {
                "min_win_rate_15d": "0.45",
                "max_win_rate_15d": "0.95",
                "min_roi_15d": "0",
                "min_total_trades_15d": "50",
                "max_total_trades_15d": "100000",
                "min_pnl_15d": "5000",
                "sort_by": "roi"
              },
              "pagination": { "limit": 10, "offset": 0 },
              "formatter_config": { "format_type": "raw" }
            }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
                headers={"Authorization": "Bearer YOUR_TOKEN"},
                json={
                    "agent_id": 584,
                    "params": {
                        "min_win_rate_15d": "0.45",
                        "max_win_rate_15d": "0.95",
                        "min_roi_15d": "0",
                        "min_total_trades_15d": "50",
                        "max_total_trades_15d": "100000",
                        "min_pnl_15d": "5000",
                        "sort_by": "roi",
                    },
                    "pagination": {"limit": 10, "offset": 0},
                    "formatter_config": {"format_type": "raw"},
                },
            )

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: |-
            const response = await fetch(
              "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
              {
                method: "POST",
                headers: {
                  Authorization: "Bearer YOUR_TOKEN",
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  agent_id: 584,
                  params: {
                    min_win_rate_15d: "0.45",
                    max_win_rate_15d: "0.95",
                    min_roi_15d: "0",
                    min_total_trades_15d: "50",
                    max_total_trades_15d: "100000",
                    min_pnl_15d: "5000",
                    sort_by: "roi",
                  },
                  pagination: { limit: 10, offset: 0 },
                  formatter_config: { format_type: "raw" },
                }),
              }
            );

            const data = await response.json();
components:
  schemas:
    PolymarketFalconLeaderboardRequest:
      type: object
      required:
        - params
      properties:
        agent_id:
          type: integer
          enum:
            - 584
          default: 584
          x-default: 584
          description: Falcon Leaderboard agent ID.
        params:
          $ref: '#/components/schemas/PolymarketFalconLeaderboardParams'
        pagination:
          $ref: '#/components/schemas/PolymarketFalconLeaderboardPagination'
        formatter_config:
          $ref: '#/components/schemas/PolymarketFalconLeaderboardFormatterConfig'
    PolymarketFalconLeaderboardResponse:
      type: object
      readOnly: true
      properties:
        timestamp:
          type: string
          readOnly: true
        params:
          $ref: '#/components/schemas/PolymarketFalconLeaderboardResponseParams'
        pagination:
          type: object
          readOnly: true
          properties:
            limit:
              type: integer
              readOnly: true
            offset:
              type: integer
              readOnly: true
            has_more:
              type: boolean
              readOnly: true
        data:
          type: object
          readOnly: true
          properties:
            results:
              type: array
              readOnly: true
              items:
                type: object
                readOnly: true
                additionalProperties: true
        request_id:
          type: string
          readOnly: true
    PolymarketFalconLeaderboardParams:
      type: object
      description: Filter parameters. All values must be strings.
      additionalProperties: false
      properties:
        min_win_rate_15d:
          type: string
          default: '0.45'
          description: Minimum 15-day win rate (0–1).
        max_win_rate_15d:
          type: string
          default: '0.95'
          description: Maximum 15-day win rate (0–1).
        min_roi_15d:
          type: string
          default: '0'
          description: Minimum 15-day ROI.
        min_total_trades_15d:
          type: string
          default: '50'
          description: Minimum trades in the last 15 days.
        max_total_trades_15d:
          type: string
          default: '100000'
          description: Maximum trades in the last 15 days.
        min_pnl_15d:
          type: string
          default: '5000'
          description: Minimum realized PnL in USD over 15 days.
        sort_by:
          type: string
          enum:
            - f_score
            - roi
            - pnl
            - win_rate
            - trades
            - sharpe
          default: roi
          description: Sort metric for ranking results.
    PolymarketFalconLeaderboardPagination:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 10
          description: Maximum number of records returned per request.
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of records to skip before returning results.
    PolymarketFalconLeaderboardFormatterConfig:
      type: object
      properties:
        format_type:
          type: string
          enum:
            - raw
          default: raw
          description: Output format. Use "raw" for structured JSON.
    PolymarketFalconLeaderboardResponseParams:
      type: object
      readOnly: true
      properties:
        min_win_rate_15d:
          type: string
          readOnly: true
        max_win_rate_15d:
          type: string
          readOnly: true
        min_roi_15d:
          type: string
          readOnly: true
        min_total_trades_15d:
          type: string
          readOnly: true
        max_total_trades_15d:
          type: string
          readOnly: true
        min_pnl_15d:
          type: string
          readOnly: true
        sort_by:
          type: string
          readOnly: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Falcon API key from the dashboard

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.