---
title: "Get a leaderboard"
method: GET
path: "/leaderboard"
tags: ["leaderboard"]
---

# Get a leaderboard

`GET /leaderboard`

## Request

- Base URL: `https://api.heytaco.com`
- URL: `https://api.heytaco.com/leaderboard`
- Auth: HTTP bearer

Returns the leaderboard for the caller's team.

## Query parameters

- `type` 'received' | 'given' | 'combined', required
- `timeframe` 'custom' | 'alltime' | 'year' | 'month' | 'week' | 'today', required
- `channel_id` string
- `timezone` string
- `start_date` string, date
- `end_date` string, date
- `limit` integer

## Response `200`

A leaderboard report.

- Leaderboard: A ranked list of users for a given team, timeframe (in the requested `timezone`), and taco-total type. Every leaderboard endpoint returns this shape.
  - `object` 'leaderboard', required: Object type. Always `leaderboard`.
  - `type` 'received' | 'given' | 'combined', required: The kind of totals ranked. One of `received`, `given`, or `combined`.
  - `timeframe` 'custom' | 'alltime' | 'year' | 'month' | 'week' | 'today', required: The window used to compute the leaderboard.
  - `timezone` string, required: The time zone the window was computed in, in canonical form (e.g. `US/Pacific` → `America/Los_Angeles`). `America/Los_Angeles` when omitted.
  - `start_date` string, date, nullable, required: `null` for `alltime`; echoed for `custom`; computed in `timezone` for named timeframes.
  - `end_date` string, date, nullable, required: `null` for `alltime`; echoed for `custom`; computed in `timezone` for named timeframes.
  - `channel_id` string, nullable, required: Echo of the request `channel_id`, or `null` when omitted.
  - `total_results` integer, required: Total number of entries available for the request, before `limit` is applied.
  - `limit` integer, nullable, required: Echo of the request `limit`, or `null` when omitted.
  - `data` LeaderboardEntry[], required: Ranked entries in descending order by `total`.
    - `rank` integer, required: 1-indexed rank in the returned window.
    - `user_id` string, required: User id in: `U...` format
    - `name` string, required: User's display name.
    - `avatar_url` string, uri, nullable, required: URL of the user's avatar image, or `null` if unset.
    - `total` integer, required: The taco total for the requested `type`.
    - `total_given` integer: Total tacos given. Only present on `combined` rows.
    - `total_received` integer: Total tacos received. Only present on `combined` rows.

## Other responses

- `400`: Request validation error.
- `401`: Authentication failed.
- `403`: The request was rejected by an access-control check. This covers requests made over plain HTTP, scope, team-level API access being disabled, and tenant-state errors returned when the team or user is no longer eligible to call the API.
- `429`: Rate limit exceeded — see `Retry-After`.
- `500`: An unexpected error on our side. Not caused by the request; safe to retry after a short delay, and reported to us automatically.
- `503`: A dependent service is unavailable. Callers should retry with backoff.

---

[API](https://skmtc.dev/heytaco/apis/heytaco-api.md) - [All operations](https://skmtc.dev/heytaco/apis/heytaco-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heytaco/apis/heytaco-api/revisions/9e5c67c64b0f?raw)