Votes
Checking whether someone voted, getting told when they do, and how votes are cast.
For cooldowns, the weekend bonus and vote credits, see the Voting Rules & FAQ on the main site. This page covers what your bot or integration can do with votes.
Checking a vote
GET /users/{uid}/{target_type}/{target_id}/votestarget_type is bot or server. This endpoint is public and needs no token,
so it's the simplest way to reward voters: when a user runs a command, check
whether they've voted.
{
"has_voted": true,
"valid_votes": [
{
"itag": "0b6a9c2e-...",
"target_type": "bot",
"target_id": "1234567890123456789",
"author": "510065483693817867",
"upvote": true,
"void": false,
"void_reason": null,
"voided_at": null,
"created_at": "2026-10-29T12:00:00Z",
"vote_num": 1,
"credit_redeem": null,
"immutable": false,
"auto": false
}
],
"vote_info": {
"per_user": 1,
"vote_time": 12,
"vote_credits": true,
"multiple_votes": true,
"supports_upvotes": true,
"supports_downvotes": false,
"supports_partial_vote_credits_redeem": true,
"weekend_bonus": false
},
"wait": { "hours": 11, "minutes": 59, "seconds": 3 }
}| Field | Notes |
|---|---|
has_voted | For listings that allow repeat votes, whether the user voted within the current vote window. Otherwise, whether they've ever voted. |
valid_votes | The user's votes that haven't been voided. vote_num is 2 for the second vote of a double vote. auto is true for votes cast by an Auto-vote subscription. |
vote_info.vote_time | Hours between votes. |
vote_info.per_user | How many votes one vote counts as. It's 2 on a double-vote weekend. |
wait | How long until the user can vote again, or null if they can vote now. |
Every SDK wraps this as hasVoted / has_voted and
getBotVote / get_bot_vote, with server versions too.
Monthly resets
Vote counts reset at the start of every month, so rankings reflect recent
votes. A reset doesn't delete anything: each vote is kept and marked
void, with a void_reason. That's why valid_votes only lists votes
from the current month, and why a listing's vote count drops to zero on
the 1st. If you show vote totals in your bot, say they're for this month.
Auto-vote
People with an Auto-vote
subscription can have Omniplex vote for them as soon as their cooldown
ends. These votes count toward your listing's votes and ranking like any
other, and they're marked auto: true in valid_votes and in the
NEW_VOTE webhook, so you can treat them differently if you want (for
example, not giving the same in-bot reward as a hand-cast vote). They
don't earn vote credits.
If you'd rather not receive automatic votes at all, turn off Accept
automatic votes in your listing's settings on the dashboard
(auto_votes_opt_out in the API).
Getting told about votes
To react to a vote the moment it happens, instead of when the user next runs a
command, set up a webhook. Each vote sends a
NEW_VOTE event with the voter, the vote count and whether it was an upvote or
an Auto-vote.
Servers can also have Infernoplex post a message in a channel for every vote, with no code at all.
Casting a vote
PUT /users/{uid}/{target_type}/{target_id}/votes?upvote=trueThis needs a user session, and user sessions are only accepted from omniplex.gg itself, so a third-party app or bot can't cast votes on a user's behalf. It's documented here so you know how votes reach your listing.
upvote is required and must be true or false. Bots and servers ask for a
Cloudflare Turnstile captcha
unless the owner has turned captchas off. When one is needed, the body is:
{ "token": "..." }where token comes from a Turnstile widget rendered with the action vote.
Each token works once. A missing, expired or invalid token gets a 400 asking
the user to complete the captcha again. Packs and teams never need one.