Get a contact's position
The live queue position, how far it is to the front, and how many referrals until the next jump, served straight from Redis so it stays fast even at a million contacts.
Requires the contacts:read scope.
Everything you need to render somebody's place in the queue.
| Field | Meaning |
|---|---|
position |
Where they are now, including any head start you configured |
to_first |
How many more referrals it would take to reach first place |
next_jump |
How many places one more referral would move them up, right now |
All three are null when the contact is not on the board, for example a signup the spam guard held
for review. The overflow lock does not affect these values: it withholds a contact's identity, not
their standing, so an over-cap contact still returns a real position.
There is a second case worth handling: on a project where a referral is configured to be worth no
points, position is a real number while to_first and next_jump are both null. Both of
those fields answer "what does one more referral buy", and on that project the honest answer is
nothing, so we return nothing rather than promising a climb that will not happen. Hide the nudge
when they are null; do not fall back to 1.
Why this is a separate endpoint#
Position is never stored. It is read live from the referral leaderboard, so it is correct the moment you ask rather than correct as of the last recalculation.
The read is O(log n), the same at a million contacts as at a hundred, which is why there is no
nightly job and no drift.