Omniplex Docs

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}/votes

target_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 }
}
FieldNotes
has_votedFor listings that allow repeat votes, whether the user voted within the current vote window. Otherwise, whether they've ever voted.
valid_votesThe 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_timeHours between votes.
vote_info.per_userHow many votes one vote counts as. It's 2 on a double-vote weekend.
waitHow 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=true

This 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.

On this page