Falcon Leaderboard

cURL

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" }
}'

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())

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();

{
  "timestamp": "<string>",
  "params": {
    "min_win_rate_15d": "<string>",
    "max_win_rate_15d": "<string>",
    "min_roi_15d": "<string>",
    "min_total_trades_15d": "<string>",
    "max_total_trades_15d": "<string>",
    "min_pnl_15d": "<string>",
    "sort_by": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {}
    ]
  },
  "request_id": "<string>"
}

POST

api

semantic

retrieve

parameterized

cURL

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" }
}'

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())

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();

{
  "timestamp": "<string>",
  "params": {
    "min_win_rate_15d": "<string>",
    "max_win_rate_15d": "<string>",
    "min_roi_15d": "<string>",
    "min_total_trades_15d": "<string>",
    "max_total_trades_15d": "<string>",
    "min_pnl_15d": "<string>",
    "sort_by": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {}
    ]
  },
  "request_id": "<string>"
}

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

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"
  }
}'

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())

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();

Authorizations

Authorization

string

header

required

Your Falcon API key from the dashboard

Body

application/json

params

object

required

Filter parameters. All values must be strings.

Hide child attributes

params.min_win_rate_15d

string

default:0.45

Minimum 15-day win rate (0–1).

params.max_win_rate_15d

string

default:0.95

Maximum 15-day win rate (0–1).

params.min_roi_15d

string

default:0

Minimum 15-day ROI.

params.min_total_trades_15d

string

default:50

Minimum trades in the last 15 days.

params.max_total_trades_15d

string

default:100000

Maximum trades in the last 15 days.

params.min_pnl_15d

string

default:5000

Minimum realized PnL in USD over 15 days.

params.sort_by

enum<string>

default:roi

Sort metric for ranking results.

Available options:

f_score,

roi,

pnl,

win_rate,

trades,

sharpe

agent_id

enum<integer>

default:584

Falcon Leaderboard agent ID.

Available options:

584

pagination

object

Hide child attributes

pagination.limit

integer

default:10

Maximum number of records returned per request.

Required range: 1 <= x <= 200

pagination.offset

integer

default:0

Number of records to skip before returning results.

Required range: x >= 0

formatter_config

object

Hide child attributes

formatter_config.format_type

enum<string>

default:raw

Output format. Use "raw" for structured JSON.

Available options:

raw

Response

Success

timestamp

string

read-only

params

object

read-only

Hide child attributes

params.min_win_rate_15d

string

read-only

params.max_win_rate_15d

string

read-only

params.min_roi_15d

string

read-only

params.min_total_trades_15d

string

read-only

params.max_total_trades_15d

string

read-only

params.min_pnl_15d

string

read-only

params.sort_by

string

read-only

pagination

object

read-only

Hide child attributes

pagination.limit

integer

read-only

pagination.offset

integer

read-only

pagination.has_more

boolean

read-only

data

object

read-only

Hide child attributes

data.results

object[]

read-only

request_id

string

read-only

Overview

Composite workflows

Polymarket

Kalshi

Social Intelligence

Falcon Leaderboard

Query parameters

Example Request

Authorizations

Body

Response

​Query parameters

​Example Request

Authorizations

Body

Response

Query parameters

Example Request