Polls

Start, stop, and get information relating to polls on a Twitch channel.

View as markdown
Provide feedback for this page

Get Polls

Polls are available for 90 days after they're created.

Endpoint

GEThttps://api.twitch.tv/helix/polls

Authorization

Requires one of the following:

  • A user access token that includes the channel:read:polls or channel:manage:polls scope.

Query Parameters

  • broadcaster_idStringRequired
    The ID of the broadcaster that created the polls. This ID must match the user ID in the user access token.
  • idString

    A list of IDs that identify the polls to return. To specify more than one ID, include this parameter for each poll you want to get. For example, 'id=1234&id=5678'. You may specify a maximum of 20 IDs.

    Specify this parameter only if you want to filter the list that the request returns. The endpoint ignores duplicate IDs and those not owned by this broadcaster.

  • firstInteger
    The maximum number of items to return per page in the response. The minimum page size is 1 item per page and the maximum is 20 items per page. The default is 20.
  • afterString
    The cursor used to get the next page of results. The Pagination object in the response contains the cursor's value. Read More

Response Body

  • dataObject[]
    A list of polls. The polls are returned in descending order of start time unless you specify IDs in the request, in which case they're returned in the same order as you passed them in the request. The list is empty if the broadcaster hasn't created polls.
    Hide child attributesShow child attributes
    • data.idString
      An ID that identifies the poll.
    • data.broadcaster_idString
      An ID that identifies the broadcaster that created the poll.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.broadcaster_loginString
      The broadcaster's login name.
    • data.titleString
      The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
    • data.choicesObject[]
      A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
      Hide child attributesShow child attributes
      • data.choices.idString
        An ID that identifies this choice.
      • data.choices.titleString
        The choice's title. The title may contain a maximum of 25 characters.
      • data.choices.votesInteger
        The total number of votes cast for this choice.
      • data.choices.channel_points_votesInteger
        The number of votes cast using Channel Points.
    • data.channel_points_voting_enabledBoolean
      A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
    • data.channel_points_per_voteInteger
      The number of points the viewer must spend to cast one additional vote.
    • data.statusString
      The poll's status.

      Possible values

      • ACTIVE
        The poll is running.
      • COMPLETED
        The poll ended on schedule (see the 'duration' field).
      • TERMINATED
        The poll was terminated before its scheduled end.
      • ARCHIVED
        The poll has been archived and is no longer visible on the channel.
      • INVALID
        Something went wrong while determining the state.
    • data.durationInteger
      The length of time (in seconds) that the poll will run for.
    • data.started_atString
      The UTC date and time (in RFC3339 format) of when the poll began.
    • data.ended_atString
      The UTC date and time (in RFC3339 format) of when the poll ended. If 'status' is ACTIVE, the object doesn't include this field.
  • paginationObject
    Contains the information used to page through the list of results. The object is empty if there are no more pages left to page through. Read More
    Hide child attributesShow child attributes
    • pagination.cursorString
      The cursor used to get the next page of results. Use the cursor to set the request's after query parameter.

Response Codes

200OK
Successfully retrieved the broadcaster's polls.
400Bad Request
  • The broadcaster_id query parameter is required.
  • The cursor specified in the after query parameter is not valid.
401Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token is missing the channel:read:polls scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.
404Not Found
  • None of the IDs in the id query parameters were found.
Request Example
curl -X GET 'https://api.twitch.tv/helix/polls?broadcaster_id=141981764&id=ed961efd-8a3f-4cf5-a9d0-e616c590cd2a' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'
Response Example
{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0
        }
      ],
      "channel_points_voting_enabled": false,
      "channel_points_per_vote": 0,
      "status": "ACTIVE",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z"
    }
  ],
  "pagination": {}
}

Create Poll

Creates a poll that viewers in the broadcaster's channel can vote on. The poll begins as soon as it's created. You may run only one poll at a time.

Endpoint

POSThttps://api.twitch.tv/helix/polls

Authorization

Requires one of the following:

Request Body

  • broadcaster_idStringRequired
    The ID of the broadcaster that's running the poll. This ID must match the user ID in the user access token.
  • titleStringRequired
    The question that viewers will vote on. For example, What game should I play next? The question may contain a maximum of 60 characters.
  • choicesObject[]Required
    A list of choices that viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 5 choices.
    Hide child attributesShow child attributes
    • choices.titleStringRequired
      One of the choices the viewer may select. The choice may contain a maximum of 25 characters.
  • durationIntegerRequired
    The length of time (in seconds) that the poll will run for. The minimum is 15 seconds and the maximum is 1800 seconds (30 minutes).
  • channel_points_voting_enabledBoolean
    A Boolean value that indicates whether viewers may cast additional votes using Channel Points. If true, the viewer may cast more than one vote but each additional vote costs the number of Channel Points specified in 'channel_points_per_vote'. The default is false (viewers may cast only one vote). For information about Channel Points, see Channel Points Guide.
  • channel_points_per_voteInteger
    The number of points that the viewer must spend to cast one additional vote. The minimum is 1 and the maximum is 1000000. Set only if 'channel_points_voting_enabled' is true.

Response Body

  • dataObject[]
    A list that contains the single poll that you created.
    Hide child attributesShow child attributes
    • data.idString
      An ID that identifies the poll.
    • data.broadcaster_idString
      An ID that identifies the broadcaster that created the poll.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.broadcaster_loginString
      The broadcaster's login name.
    • data.titleString
      The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
    • data.choicesObject[]
      A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
      Hide child attributesShow child attributes
      • data.choices.idString
        An ID that identifies this choice.
      • data.choices.titleString
        The choice's title. The title may contain a maximum of 25 characters.
      • data.choices.votesInteger
        The total number of votes cast for this choice.
      • data.choices.channel_points_votesInteger
        The number of votes cast using Channel Points.
    • data.channel_points_voting_enabledBoolean
      A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
    • data.channel_points_per_voteInteger
      The number of points the viewer must spend to cast one additional vote.
    • data.statusString
      The poll's status.

      Possible values

      • ACTIVE
        The poll is running.
      • COMPLETED
        The poll ended on schedule (see the 'duration' field).
      • TERMINATED
        The poll was terminated before its scheduled end.
      • ARCHIVED
        The poll has been archived and is no longer visible on the channel.
      • MODERATED
        The poll was deleted.
      • INVALID
        Something went wrong while determining the state.
    • data.durationInteger
      The length of time (in seconds) that the poll will run for.
    • data.started_atString
      The UTC date and time (in RFC3339 format) of when the poll began.
    • data.ended_atString
      The UTC date and time (in RFC3339 format) of when the poll ended. If 'status' is ACTIVE, the object doesn't include this field.

Response Codes

200OK
Successfully created the poll.
400Bad Request
  • The broadcaster_id field is required.
  • The 'title' field is required.
  • The 'choices' field is required.
  • The 'duration' field is required.
  • The value in 'duration' is outside the allowed range of values.
  • The value in 'channel_points_per_vote' is outside the allowed range of values.
  • The 'channel_points_voting_enabled' field is true, but the broadcaster doesn't have Channel Points enabled.
  • The poll's 'title' is too long.
  • The choice's 'title' is too long.
  • The choice's 'title' failed AutoMod checks.
  • The number of choices in the poll may not be less than 2 or greater that 5.
  • The broadcaster already has a poll that's running; you may not create another poll until the current poll completes.
401Unauthorized
  • The ID in broadcaster_id must match the user ID in the access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token is missing the channel:manage:polls scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header does not match the client ID specified in the access token.
403Forbidden
  • The broadcaster is not a partner or affiliate.
Request Example
curl -X POST 'https://api.twitch.tv/helix/polls' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"broadcaster_id":"141981764","title":"Heads or Tails?","choices":[{"title":"Heads"},{"title":"Tails"}],"channel_points_voting_enabled":true,"channel_points_per_vote":100,"duration":1800}'
Response Example
{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0
        }
      ],
      "channel_points_voting_enabled": true,
      "channel_points_per_vote": 100,
      "status": "ACTIVE",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z"
    }
  ]
}

End Poll

Ends an active poll. You have the option to end it or end it and archive it.

Endpoint

PATCHhttps://api.twitch.tv/helix/polls

Authorization

Requires one of the following:

Request Body

  • broadcaster_idStringRequired
    The ID of the broadcaster that's running the poll. This ID must match the user ID in the user access token.
  • idStringRequired
    The ID of the poll to update.
  • statusStringRequired
    The status to set the poll to.

    Possible values

    • TERMINATED
      Ends the poll before the poll is scheduled to end. The poll remains publicly visible.
    • ARCHIVED
      Ends the poll before the poll is scheduled to end, and then archives it so it's no longer publicly visible.

Response Body

  • dataObject[]
    A list that contains the poll that you ended.
    Hide child attributesShow child attributes
    • data.idString
      An ID that identifies the poll.
    • data.broadcaster_idString
      An ID that identifies the broadcaster that created the poll.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.broadcaster_loginString
      The broadcaster's login name.
    • data.titleString
      The question that viewers are voting on. For example, What game should I play next? The title may contain a maximum of 60 characters.
    • data.choicesObject[]
      A list of choices that viewers can choose from. The list will contain a minimum of two choices and up to a maximum of five choices.
      Hide child attributesShow child attributes
      • data.choices.idString
        An ID that identifies this choice.
      • data.choices.titleString
        The choice's title. The title may contain a maximum of 25 characters.
      • data.choices.votesInteger
        The total number of votes cast for this choice.
      • data.choices.channel_points_votesInteger
        The number of votes cast using Channel Points.
    • data.channel_points_voting_enabledBoolean
      A Boolean value that indicates whether viewers may cast additional votes using Channel Points. For information about Channel Points, see Channel Points Guide.
    • data.channel_points_per_voteInteger
      The number of points the viewer must spend to cast one additional vote.
    • data.statusString
      The poll's status.

      Possible values

      • ACTIVE
        The poll is running.
      • COMPLETED
        The poll ended on schedule (see the 'duration' field).
      • TERMINATED
        The poll was terminated before its scheduled end.
      • ARCHIVED
        The poll has been archived and is no longer visible on the channel.
      • MODERATED
        The poll was deleted.
      • INVALID
        Something went wrong while determining the state.
    • data.durationInteger
      The length of time (in seconds) that the poll will run for.
    • data.started_atString
      The UTC date and time (in RFC3339 format) of when the poll began.
    • data.ended_atString
      The UTC date and time (in RFC3339 format) of when the poll ended. If 'status' is ACTIVE, the object doesn't include this field.

Response Codes

200OK
Successfully ended the poll.
400Bad Request
  • The broadcaster_id field is required.
  • The 'id' field is required.
  • The 'status' field is required.
  • The value in the 'status' field is not valid.
  • To terminate the poll, its status must be ACTIVE.
  • To archive the poll, its status must be ACTIVE, COMPLETED, or TERMINATED.
401Unauthorized
  • The ID in broadcaster_id must match the user ID in the user access token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:polls scope.
  • The access token is not valid.
  • The client ID specified in the Client-Id header must match the client ID specified in the access token.
403Forbidden
  • The poll in the 'id' field belongs to another broadcaster.
  • The poll in the 'id' field was deleted (its status is MODERATED).
404Not Found
  • The poll in the 'id' field was not found.
Request Example
curl -X PATCH 'https://api.twitch.tv/helix/polls' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"broadcaster_id":"141981764","id":"ed961efd-8a3f-4cf5-a9d0-e616c590cd2a","status":"TERMINATED"}'
Response Example
{
  "data": [
    {
      "id": "ed961efd-8a3f-4cf5-a9d0-e616c590cd2a",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Heads or Tails?",
      "choices": [
        {
          "id": "4c123012-1351-4f33-84b7-43856e7a0f47",
          "title": "Heads",
          "votes": 0,
          "channel_points_votes": 0
        },
        {
          "id": "279087e3-54a7-467e-bcd0-c1393fcea4f0",
          "title": "Tails",
          "votes": 0,
          "channel_points_votes": 0
        }
      ],
      "channel_points_voting_enabled": true,
      "channel_points_per_vote": 100,
      "status": "TERMINATED",
      "duration": 1800,
      "started_at": "2021-03-19T06:08:33.871278372Z",
      "ended_at": "2021-03-19T06:11:26.746889614Z"
    }
  ]
}