poll_get

Fetch one poll by ID. Use it to show up-to-date results, or to learn which options the signed-in user has picked.

Poll events such as poll_vote carry totals but not your own selection, so call poll_get when you need it. Polls are created as a message embed; see polls.

Request

{
  "cmd": "poll_get",
  "poll_id": "3c9d2f61-5b7e-4a0f-9e2c-1d8a6b4f0e57"
}

Field	Type	Required	Description
`poll_id`	string	Yes	ID of the poll. Read it from `embeds[].poll.id` on the message that holds the poll. Surrounding spaces are trimmed.

Response

{
  "cmd": "poll_get",
  "poll": {
    "id": "3c9d2f61-5b7e-4a0f-9e2c-1d8a6b4f0e57",
    "message_id": "8f14e45f-ceea-467a-9575-3d3b4c1b2a10",
    "channel": "general",
    "thread_id": null,
    "question": "When should we meet?",
    "options": [
      { "id": "0", "text": "Monday" },
      { "id": "1", "text": "Tuesday", "emoji": "📅" }
    ],
    "allow_multiselect": false,
    "expires_at": 1788710400,
    "created_at": 1788624000,
    "ended": false,
    "ended_at": null,
    "created_by": "alice",
    "user_votes": ["1"],
    "total_votes": 3,
    "results": [
      { "id": "0", "text": "Monday", "votes": 1, "voters": ["bob"], "voted": false },
      { "id": "1", "text": "Tuesday", "emoji": "📅", "votes": 2, "voters": ["alice", "carol"], "voted": true }
    ]
  }
}

Field	Description
`thread_id`	The thread that holds the poll, or `null` for a channel poll.
`options`	The choices. Option IDs are `"0"`, `"1"`, and so on, in creation order. `emoji` appears only if the creator set one.
`expires_at`	When voting closes, in Unix seconds, or `null` if the poll has no end time.
`ended`, `ended_at`	Whether the poll is closed, and when (Unix seconds, or `null`). A poll past its `expires_at` is marked ended when it is next read.
`created_by`	Username of the poll’s creator.
`user_votes`	Option IDs you have selected. Empty if you haven’t voted.
`total_votes`	Sum of `votes` across all options. On a multiple-choice poll one user can add more than one.
`results`	One entry per option, with `votes` (a count), `voters` (usernames), and `voted` (whether you picked it).

This response goes to the caller only.

Permissions

You need to be able to view the channel, or the parent forum of the thread, that holds the poll.

Errors

`val`	When
`Poll not found`	No poll has this ID.
`Access denied to this channel`	You can’t view the poll’s channel.
`You do not have permission to view this thread`	You can’t view the parent forum of the poll’s thread.
`Channel not found` or `Thread not found`	The poll’s channel or thread no longer exists.
Validation message	`poll_id` is missing, not a string, or blank, for example `poll_id: Required`.

See also