Retrieve user (beta)

Retrieve leaderboard details for selected user.

HABS leaderboard schema: https://www.notion.so/HABS-Leaderboard-API-Response-Structure-2a5aaa85799880d1b04ac33791575f40

Get user's leaderboard entry

get

Retrieve a specific user's entry from a leaderboard. Can lookup by FID or wallet address. Returns latest entry by default, or all historical entries if run_timestamp=all.

Path parameters

leaderboard_namestringRequired

Name of the leaderboard to retrieve

Query parameters

api_keystringRequired

API key for authentication

fidany ofOptional

Farcaster ID (FID) of the user to look up

integerOptional

or

nullOptional

wallet_addressany ofOptional

Wallet address to look up (will resolve to FID)

stringOptional

or

nullOptional

run_timestampstringOptional

Optional: 'all' to get all historical entries, omit for latest only

Responses

200

Successfully retrieved user leaderboard data

application/json

401

Unauthorized - Invalid API key

404

Leaderboard not found or user not in leaderboard

422

Validation Error

application/json

500

Internal Server Error

get

/v1/leaderboard/{leaderboard_name}/user

HTTPcURLJavaScriptPython

GET /v1/leaderboard/{leaderboard_name}/user?api_key=text HTTP/1.1
Accept: */*

{
  "leaderboard_name": "text",
  "user_identifier": "text",
  "data": null,
  "found": true,
  "run_timestamp": "2026-02-05T00:10:57.823Z",
  "run_timestamps": [
    "2026-02-05T00:10:57.823Z"
  ]
}