Cohort ladders

The canonical cohort ladders as flat label sets — the exact strings ?cohort= accepts.

GET https://data.vike.io/v1/hl-cohorts/cohorts

The canonical cohort ladders as flat label sets — the exact strings ?cohort= accepts. Takes no parameters. The shape is {"size": [...12], "pnl": [...12, "unknown"], "tier": [...10], "pnl_abs": [...8, "unknown"]}, and it is served from the same label sets the axes group by and ?cohort= is validated against — so a label is accepted on its axis if and only if it appears here (its /segments slug is accepted in its place).

unknown rides both PnL sets because it is a real, queryable bucket there, not a rung of a ladder: on pnl it holds the wallets under 10 closed trades, on pnl_abs the wallets with no realized record at all. tier is the per-position ladder that /segments publishes as trade_size.

cURL

# the exact label strings every ?cohort= accepts, per ladder
curl -s "https://data.vike.io/v1/hl-cohorts/cohorts" \
  -H "X-API-KEY: $VIKE_API_KEY"

# the dollar-banded pnl_abs ladder with its slugs and bounds: /cohorts carries the labels only, /segments the bounds
curl -s "https://data.vike.io/v1/hl-cohorts/segments" \
  -H "X-API-KEY: $VIKE_API_KEY" \
  | jq '[.[] | select(.axis == "pnl_abs") | {cohort, slug, min_usd, max_usd}]'

# the per-position tier ladder, largest first: the spellings axis=tier returns on /symbols/{symbol}/cohort-metrics
curl -s "https://data.vike.io/v1/hl-cohorts/cohorts" \
  -H "X-API-KEY: $VIKE_API_KEY" \
  | jq '.tier'

# a label with a space or a symbol is awkward in a URL path: the slug stands in for it
curl -s "https://data.vike.io/v1/hl-cohorts/segments/3x_smart/summary?axis=pnl" \
  -H "X-API-KEY: $VIKE_API_KEY"

Example response

{
  "size": [
    "4x whale",
    "3x whale",
    "2x whale",
    "whale",
    "2x shark",
    "shark",
    "2x dolphin",
    "dolphin",
    "2x fish",
    "fish",
    "2x shrimp",
    "shrimp"
  ],
  "pnl": [
    "3x smart",
    "2x smart",
    "smart",
    "3x winner",
    "2x winner",
    "winner",
    "loser",
    "2x loser",
    "3x loser",
    "rekt",
    "2x rekt",
    "3x rekt",
    "unknown"
  ],
  "tier": [
    ">$2.5m",
    "$1m-$2.5m",
    "$500k-$1m",
    "$250k-$500k",
    "$100k-$250k",
    "$50k-$100k",
    "$25k-$50k",
    "$10k-$25k",
    "$1k-$10k",
    "<$1k"
  ],
  "pnl_abs": [
    "$1m+",
    "$100k-$1m",
    "$10k-$100k",
    "$0-$10k",
    "-$10k-$0",
    "-$100k--$10k",
    "-$1m--$100k",
    "<-$1m",
    "unknown"
  ]
}

tier is a key here, not an axis every route groups by

tier is the per-position ladder: /symbols/{symbol}/cohort-metrics groups by it as axis=tier (or trade_size, the name /segments gives it), while the per-wallet routes, /heatmap and /segments/{cohort}/summary, refuse it. A client that generates calls from these keys should filter on groupable in /segments first.