The Leaderboard object | HeyTaco API Documentation

A ranked list of users for a given team, timeframe (in the requested timezone), and taco-total type. Every leaderboard endpoint returns this shape.

Attributes

objectstring

Object type. Always leaderboard.

typestring

The kind of totals ranked. One of received, given, or combined.

timeframestring

The window used to compute the leaderboard.

timezonestring

The time zone the window was computed in, in canonical form (e.g. US/Pacific → America/Los_Angeles). America/Los_Angeles when omitted.

start_datestring or null

null for alltime; echoed for custom; computed in timezone for named timeframes.

end_datestring or null

null for alltime; echoed for custom; computed in timezone for named timeframes.

channel_idstring or null

Echo of the request channel_id, or null when omitted.

total_resultsinteger

Total number of entries available for the request, before limit is applied.

limitinteger or null

Echo of the request limit, or null when omitted.

dataarray of leaderboard_entry

Ranked entries in descending order by total.

Show child attributes

rankinteger

1-indexed rank in the returned window.

user_idstring

User id in: U... format

namestring

User's display name.

avatar_urlstring or null

URL of the user's avatar image, or null if unset.

totalinteger

The taco total for the requested type.

total_givenintegeroptional

Total tacos given. Only present on combined rows.

total_receivedintegeroptional

Total tacos received. Only present on combined rows.

The Leaderboard object

{
  "object": "leaderboard",
  "type": "received",
  "timeframe": "month",
  "timezone": "America/Los_Angeles",
  "start_date": "2026-08-01",
  "end_date": "2026-08-31",
  "channel_id": null,
  "total_results": 42,
  "limit": null,
  "data": [
    {
      "rank": 1,
      "user_id": "U012ABCDEF",
      "name": "Angus",
      "avatar_url": "https://avatars.slack-edge.com/U012ABCDEF.png",
      "total": 128
    },
    {
      "rank": 2,
      "user_id": "U345GHIJKL",
      "name": "Fitz",
      "avatar_url": "https://avatars.slack-edge.com/U345GHIJKL.png",
      "total": 96
    },
    {
      "rank": 3,
      "user_id": "U678MNOPQR",
      "name": "Koko",
      "avatar_url": null,
      "total": 84
    }
  ]
}