How do I check Hyperliquid cohort data is fresh before I trade on it?

Read the freshness block of /symbols/{symbol}/cohort-metrics; stale is true when the newest hourly bucket is more than 3 hours behind, and the 5-minute snapshot time is latest.ts on /indices.

GET /v1/hl-cohorts/symbols/{symbol}/cohort-metrics answers it in one call. Ask for the newest hour without an end and the envelope carries freshness: the newest bucket's newest_ts, how many whole hours it is behind_hours the current hour, the settled_lag_ceiling_hours the service allows, and a stale verdict you can test in one line. The full parameter list is on Coin cohort metrics, and Freshness explains the block.

Quick answer

No end, so the window reaches the present and the block is there.

cURL

# the newest settled hour of BTC's cohort matrix, with the freshness verdict in the envelope
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/hl-cohorts/symbols/BTC/cohort-metrics?hours=1"

Example response

Captured from the live API on 2026-10-24 at 17:15 UTC, trimmed to 1 row of 12 (one per size cohort). At 17:15 the newest settled hour was 16:00, one hour behind the current hour, so stale is false. A bucket up to two hours behind is healthy, and stale turns true only above the ceiling of 3. Refuse to trade on the matrix while stale is true.

Example response

{
  "axis": "size",
  "label_basis": "point_in_time",
  "metrics": [
    {
      "ts": "2026-10-24T16:00:00+00:00",
      "cohort": "4x whale",
      "position_count": 22,
      "position_count_long": 7,
      "total_position_value": 1163976506.0,
      "total_position_value_long": 246682718.2,
      "total_unrealized_pnl": -7969237.26,
      "total_position_size": 14570.28685,
      "total_position_size_long": 3087.89563,
      "bias": -0.576137977,
      "label_basis": "point_in_time",
      "grading": null
    }
  ],
  "hours": 1,
  "nextCursor": "eyJtIjoiY29ob3J0X21ldHJpY3MiLCJ0IjoiMjAyNi0xMC0yNCAxNjowMDowMCJ9",
  "grading": null,
  "freshness": {
    "newest_ts": "2026-10-24T16:00:00+00:00",
    "behind_hours": 1,
    "settled_lag_ceiling_hours": 3,
    "stale": false
  }
}

Variations

The 5-minute snapshot time. latest.ts on /indices is the newest 5-minute position snapshot; compare it with your clock. It read 17:07 at a 17:14 UTC capture.

cURL — snapshot time

# the time of the newest 5-minute snapshot
curl -s -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/hl-cohorts/symbols/BTC/indices?hours=1" \
  | jq '.latest.ts'

The latest positions file. The archive index says when the 5-minute positions file was last written: snapshot_ts was 17:07 and generated_at 17:12:20 at capture.

cURL — archive

# the newest snapshot in the latest positions file and when the file was written
curl -s -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/hyperliquid/archive/datasets" \
  | jq '.latest.positions | {snapshot_ts, generated_at}'

The hour in progress. /symbols/{symbol}/metrics adds one provisional row for the hour still in progress, so it trails the clock by minutes rather than hours. Drop that row before you store the series.

cURL — provisional row

# the two newest hourly rows of BTC, the first one provisional
curl -H "X-API-Key: $VIKE_API_KEY" \
  "https://data.vike.io/v1/hl-cohorts/symbols/BTC/metrics?limit=2"

Before you rely on it

No freshness block is not the same as fresh

freshness appears only on a window that reaches the present: a request with an end in the past gets none, so test for the key before you read stale. grading=realized-pit reads a frozen research set and comes back days behind in the same shape as a live answer; only freshness tells them apart. The hourly series of /segments/{cohort}/history and the series of /indices can still change after an hour first appears: on 2026-10-24 the whale cohort's 16:00 row read $1.164B long at 17:15 UTC and $1.143B at 17:19 UTC.

Ask your agent

Connected to the Vike MCP server (https://vike.io/mcp) in Claude, ChatGPT or Cursor, ask it in plain words. The hl_cohort_metrics tool answers, at 1 credit a call.

Ask your agent

Is the Hyperliquid cohort data for BTC fresh right now? Show the freshness block

How do I check Hyperliquid cohort data is fresh before I trade on it?

Quick answer

Example response

Variations

Before you rely on it

Ask your agent

Related