Skip to main content
GET
One leaderboard: the leaders, the caller's neighbourhood, and where the caller stands.

Authorizations

X-CB-KEY
string
header
required

CloseBot API Key Authorization

Query Parameters

scope
string
default:source

"source" ranks individual sources, "agency" ranks whole accounts.

metric
string
default:bookings

A key from GET /leaderboard/metrics.

compare
string
default:all

Who to rank against: "all" (default), or "industry" for the subject's own vertical.

A mode, not an industry key. The server resolves which vertical the subject belongs to, so a caller can ask to be compared within it without ever learning — or naming — which one it is. Not valid with scope=agency: industry is a property of a source. Falls back to "all" when no board was published for the subject's vertical this period, which Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.IndustryAvailable reports.

period
string
default:current

"current" (default) or "previous".

entityId
string

Which of the caller's own entities Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.Me, Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.Around and the eligibility describe. Defaults to their best-placed one. Ignored at agency scope, where the caller has exactly one entity. A source belonging to another agency is rejected.

limit
integer<int32>
default:10

How many leaders to return. 1-10, default 10.

around
integer<int32>
default:5

How many neighbours either side of the caller. 0-5, default 5.

Response

OK

period
object
required

The calendar month a board covers.

Start and key only. The period type was always "month", the end is always one month past the start, and the client formats its own month label in the user's locale — a server-side "September 2026" is English for everybody.

cohort
object
required

The peer group a rank is relative to.

industryAvailable
boolean
required

Whether a same-industry board exists for this subject, metric and period — and so whether that comparison can be chosen.

Deliberately a boolean. Answering "is there one" is the whole of what a client needs; answering "which one" is the disclosure this endpoint will not make.

top
object[] | null
required

The leading entities, for the podium and the top-of-board view.

around
object[] | null
required

The window around the caller's best-placed entity. Empty when the caller is not on this board. This, not Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.Top, is the view most users should land on — the next rank up has to look reachable.

eligibility
object
required

Why the caller is or is not on a board.

industryLockReason
string | null

Why the comparison cannot be chosen, when it cannot. Null when it can.

"needsVolume" — the source has not been seen enough for us to classify it yet, and Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.IndustryMessagesCurrent counts toward Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.IndustryMessagesRequired.

"notYet" — anything else, and deliberately incurious. A source can be past the threshold but waiting on the next batch, examined and found unclassifiable, classified too tentatively to publish, or classified fine but in a vertical with too few ranked participants to build a board from. The client is told the comparison is unavailable and not invited to guess which — the last of those cases in particular would hint at how many participants a vertical has.

industryMessagesCurrent
integer<int64> | null

Inbound messages this source has, when Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.IndustryLockReason is "needsVolume". The caller's own figure for their own source.

industryMessagesRequired
integer<int64> | null

Inbound messages needed before a first classification is attempted, when Closebot.Api.Controllers.LeaderboardController.GetBoardResponse.IndustryLockReason is "needsVolume".

me
object

Where the caller sits on this board.

A percentile and a movement, never an absolute rank — a rank alongside the percentile solves for the cohort size, and a rank on its own still tells the worst-placed tenant roughly how many there are.