Predictions

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

View as markdown
Provide feedback for this page

Get Predictions

Gets a list of Channel Points Predictions that the broadcaster created.

Endpoint

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

Authorization

Requires one of the following:

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

Query Parameters

  • broadcaster_idStringRequired
    The ID of the broadcaster whose predictions you want to get. This ID must match the user ID in the user access token.
  • idString
    The ID of the prediction to get. To specify more than one ID, include this parameter for each prediction you want to get. For example, 'id=1234&id=5678'. You may specify a maximum of 25 IDs. The endpoint ignores duplicate IDs and those not owned by the 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 25 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[]
    The broadcaster's list of Channel Points Predictions. The list is sorted in descending order by when the prediction began (the most recent prediction is first) unless you specify IDs in the request, in which case the predictions are in the same order as the IDs. The list is empty if the broadcaster hasn't created predictions.
    Hide child attributesShow child attributes
    • data.idString
      An ID that identifies this prediction.
    • data.broadcaster_idString
      An ID that identifies the broadcaster that created the prediction.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.broadcaster_loginString
      The broadcaster's login name.
    • data.titleString
      The question that the prediction asks. For example, Will I finish this entire pizza?
    • data.winning_outcome_idString
      The ID of the winning outcome. Is null unless 'status' is RESOLVED.
    • data.outcomesObject[]
      The list of possible outcomes for the prediction.
      Hide child attributesShow child attributes
      • data.outcomes.idString
        An ID that identifies this outcome.
      • data.outcomes.titleString
        The outcome's text.
      • data.outcomes.usersInteger
        The number of unique viewers that chose this outcome.
      • data.outcomes.channel_pointsInteger
        The number of Channel Points spent by viewers on this outcome.
      • data.outcomes.top_predictorsObject[]
        A list of viewers who were the top predictors; otherwise, null if none.
        Hide child attributesShow child attributes
        • data.outcomes.top_predictors.user_idString
          An ID that identifies the viewer.
        • data.outcomes.top_predictors.user_nameString
          The viewer's display name.
        • data.outcomes.top_predictors.user_loginString
          The viewer's login name.
        • data.outcomes.top_predictors.channel_points_usedInteger
          The number of Channel Points the viewer spent.
        • data.outcomes.top_predictors.channel_points_wonInteger
          The number of Channel Points distributed to the viewer.
      • data.outcomes.colorString
        The color that visually identifies this outcome in the UX.

        Possible values

        • BLUE
        • PINK
    • data.prediction_windowInteger
      The length of time (in seconds) that the prediction will run for.
    • data.statusString
      The prediction's status.

      Possible values

      • ACTIVE
        The Prediction is running and viewers can make predictions.
      • CANCELED
        The broadcaster canceled the Prediction and refunded the Channel Points to the participants.
      • LOCKED
        The broadcaster locked the Prediction, which means viewers can no longer make predictions.
      • RESOLVED
        The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
    • data.created_atString
      The UTC date and time of when the Prediction began.
    • data.ended_atString
      The UTC date and time of when the Prediction ended. If 'status' is ACTIVE, this is set to null.
    • data.locked_atString
      The UTC date and time of when the Prediction was locked. Is null if the Prediction hasn't been locked.
  • 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 list of predictions.
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 must include the channel:read:predictions 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.
Request Example
curl -X GET 'https://api.twitch.tv/helix/predictions?broadcaster_id=55696719&id=d6676d5c-c86e-44d2-bfc4-100fb48f0656' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID'
Response Example
{
  "data": [
    {
      "id": "d6676d5c-c86e-44d2-bfc4-100fb48f0656",
      "broadcaster_id": "55696719",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Will there be any leaks today?",
      "winning_outcome_id": null,
      "outcomes": [
        {
          "id": "021e9234-5893-49b4-982e-cfe9a0aaddd9",
          "title": "Yes",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "ded84c26-13cb-4b48-8cb5-5bae3ec3a66e",
          "title": "No",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 600,
      "status": "ACTIVE",
      "created_at": "2021-04-28T16:03:06.320848689Z",
      "ended_at": null,
      "locked_at": null
    }
  ],
  "pagination": {}
}

Create Prediction

Creates a Channel Points Prediction.

With a Channel Points Prediction, the broadcaster poses a question and viewers try to predict the outcome. The prediction runs as soon as it's created. The broadcaster may run only one prediction at a time.

Endpoint

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

Authorization

Requires one of the following:

Request Body

  • broadcaster_idStringRequired
    The ID of the broadcaster that's running the prediction. This ID must match the user ID in the user access token.
  • titleStringRequired
    The question that the broadcaster is asking. For example, Will I finish this entire pizza? The title is limited to a maximum of 45 characters.
  • outcomesObject[]Required
    The list of possible outcomes that the viewers may choose from. The list must contain a minimum of 2 choices and up to a maximum of 10 choices.
    Hide child attributesShow child attributes
    • outcomes.titleStringRequired
      The text of one of the outcomes that the viewer may select. The title is limited to a maximum of 25 characters.
  • prediction_windowIntegerRequired
    The length of time (in seconds) that the prediction will run for. The minimum is 1 second and the maximum is 1800 seconds (30 minutes).

Response Body

  • dataObject[]
    A list that contains the single prediction that you created.
    Hide child attributesShow child attributes
    • data.idString
      An ID that identifies this prediction.
    • data.broadcaster_idString
      An ID that identifies the broadcaster that created the prediction.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.broadcaster_loginString
      The broadcaster's login name.
    • data.titleString
      The question that the prediction asks. For example, Will I finish this entire pizza?
    • data.winning_outcome_idString
      The ID of the winning outcome. Is null unless 'status' is RESOLVED.
    • data.outcomesObject[]
      The list of possible outcomes for the prediction.
      Hide child attributesShow child attributes
      • data.outcomes.idString
        An ID that identifies this outcome.
      • data.outcomes.titleString
        The outcome's text.
      • data.outcomes.usersInteger
        The number of unique viewers that chose this outcome.
      • data.outcomes.channel_pointsInteger
        The number of Channel Points spent by viewers on this outcome.
      • data.outcomes.top_predictorsObject[]
        A list of viewers who were the top predictors; otherwise, null if none.
        Hide child attributesShow child attributes
        • data.outcomes.top_predictors.user_idString
          An ID that identifies the viewer.
        • data.outcomes.top_predictors.user_nameString
          The viewer's display name.
        • data.outcomes.top_predictors.user_loginString
          The viewer's login name.
        • data.outcomes.top_predictors.channel_points_usedInteger
          The number of Channel Points the viewer spent.
        • data.outcomes.top_predictors.channel_points_wonInteger
          The number of Channel Points distributed to the viewer.
      • data.outcomes.colorString
        The color that visually identifies this outcome in the UX. If the prediction has two outcomes, the first outcome is BLUE and the second is PINK. If it has more than two outcomes, all of them are BLUE.

        Possible values

        • BLUE
        • PINK
    • data.prediction_windowInteger
      The length of time (in seconds) that the prediction will run for.
    • data.statusString
      The prediction's status.

      Possible values

      • ACTIVE
        The Prediction is running and viewers can make predictions.
      • CANCELED
        The broadcaster canceled the Prediction and refunded the Channel Points to the participants.
      • LOCKED
        The broadcaster locked the Prediction, which means viewers can no longer make predictions.
      • RESOLVED
        The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
    • data.created_atString
      The UTC date and time of when the Prediction began.
    • data.ended_atString
      The UTC date and time of when the Prediction ended. If 'status' is ACTIVE, this is set to null.
    • data.locked_atString
      The UTC date and time of when the Prediction was locked. Is null if the Prediction hasn't been locked.

Response Codes

200OK
Successfully created the Channel Points Prediction.
400Bad Request
  • The broadcaster_id field is required.
  • The 'title' field is required.
  • The 'outcomes' field is required.
  • The 'prediction_window' field is required.
  • The value in 'prediction_window' is outside the allowed range of values.
  • The prediction's 'title' is too long.
  • The outcome's 'title' field is required.
  • The outcome's 'title' is too long.
  • The outcome's 'title' failed AutoMod checks.
  • The number of outcomes in the prediction may not be less than 2 or greater than 10.
  • The broadcaster must have Channel Points enabled.
  • The broadcaster already has a prediction that's running; you may not create another prediction until the current prediction is resolved or canceled.
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 must include the channel:manage:predictions 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.
429Too Many Requests
Request Example
curl -X POST 'https://api.twitch.tv/helix/predictions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"broadcaster_id":"141981764","title":"Any leeks in the stream?","outcomes":[{"title":"Yes, give it time."},{"title":"Definitely not."}],"prediction_window":120}'
Response Example
{
  "data": [
    {
      "id": "bc637af0-7766-4525-9308-4112f4cbf178",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Any leeks in the stream?",
      "winning_outcome_id": null,
      "outcomes": [
        {
          "id": "73085848-a94d-4040-9d21-2cb7a89374b7",
          "title": "Yes, give it time.",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "906b70ba-1f12-47ea-9e95-e5f93d20e9cc",
          "title": "Definitely not.",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 120,
      "status": "ACTIVE",
      "created_at": "2021-04-28T17:11:22.595914172Z",
      "ended_at": null,
      "locked_at": null
    }
  ]
}

End Prediction

Locks, resolves, or cancels a Channel Points Prediction.

Endpoint

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

Authorization

Requires one of the following:

Request Body

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

    Possible values

    • RESOLVED
      The winning outcome is determined and the Channel Points are distributed to the viewers who predicted the correct outcome.
    • CANCELED
      The broadcaster is canceling the prediction and sending refunds to the participants.
    • LOCKED
      The broadcaster is locking the prediction, which means viewers may no longer make predictions.
  • winning_outcome_idString
    The ID of the winning outcome. You must set this parameter if you set 'status' to RESOLVED.

Response Body

  • dataObject[]
    A list that contains the single prediction that you updated.
    Hide child attributesShow child attributes
    • data.idString
      An ID that identifies this prediction.
    • data.broadcaster_idString
      An ID that identifies the broadcaster that created the prediction.
    • data.broadcaster_nameString
      The broadcaster's display name.
    • data.broadcaster_loginString
      The broadcaster's login name.
    • data.titleString
      The question that the prediction asks. For example, Will I finish this entire pizza?
    • data.winning_outcome_idString
      The ID of the winning outcome. Is null unless 'status' is RESOLVED.
    • data.outcomesObject[]
      The list of possible outcomes for the prediction.
      Hide child attributesShow child attributes
      • data.outcomes.idString
        An ID that identifies this outcome.
      • data.outcomes.titleString
        The outcome's text.
      • data.outcomes.usersInteger
        The number of unique viewers that chose this outcome.
      • data.outcomes.channel_pointsInteger
        The number of Channel Points spent by viewers on this outcome.
      • data.outcomes.top_predictorsObject[]
        A list of viewers who were the top predictors; otherwise, null if none.
        Hide child attributesShow child attributes
        • data.outcomes.top_predictors.user_idString
          An ID that identifies the viewer.
        • data.outcomes.top_predictors.user_nameString
          The viewer's display name.
        • data.outcomes.top_predictors.user_loginString
          The viewer's login name.
        • data.outcomes.top_predictors.channel_points_usedInteger
          The number of Channel Points the viewer spent.
        • data.outcomes.top_predictors.channel_points_wonInteger
          The number of Channel Points distributed to the viewer.
      • data.outcomes.colorString
        The color that visually identifies this outcome in the UX.

        Possible values

        • BLUE
        • PINK
    • data.prediction_windowInteger
      The length of time (in seconds) that the prediction will run for.
    • data.statusString
      The prediction's status.

      Possible values

      • ACTIVE
        The Prediction is running and viewers can make predictions.
      • CANCELED
        The broadcaster canceled the Prediction and refunded the Channel Points to the participants.
      • LOCKED
        The broadcaster locked the Prediction, which means viewers can no longer make predictions.
      • RESOLVED
        The winning outcome was determined and the Channel Points were distributed to the viewers who predicted the correct outcome.
    • data.created_atString
      The UTC date and time of when the Prediction began.
    • data.ended_atString
      The UTC date and time of when the Prediction ended. If 'status' is ACTIVE, this is set to null.
    • data.locked_atString
      The UTC date and time of when the Prediction was locked. Is null if the Prediction hasn't been locked.

Response Codes

200OK
Successfully ended the prediction.
400Bad Request
  • The broadcaster_id field is required.
  • The 'id' field is required.
  • The 'status' field is required.
  • The 'winning_outcome_id' field is required if 'status' is RESOLVED.
  • The value in the 'status' field is not valid.
  • To update the prediction's status to RESOLVED or CANCELED, its current status must be ACTIVE or LOCKED.
  • To update the prediction's status to LOCKED, its current status must be ACTIVE.
401Unauthorized
  • The ID in broadcaster_id must match the user ID in the OAuth token.
  • The Authorization header is required and must contain a user access token.
  • The user access token must include the channel:manage:predictions 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 prediction in the 'id' field belongs to another broadcaster.
404Not Found
  • The prediction in the 'id' field was not found.
  • The outcome in the 'winning_outcome_id' field was not found.
Request Example
curl -X PATCH 'https://api.twitch.tv/helix/predictions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Client-Id: YOUR_CLIENT_ID' \
  -H 'Content-Type: application/json' \
  -d '{"broadcaster_id":"141981764","id":"bc637af0-7766-4525-9308-4112f4cbf178","status":"RESOLVED","winning_outcome_id":"73085848-a94d-4040-9d21-2cb7a89374b7"}'
Response Example
{
  "data": [
    {
      "id": "bc637af0-7766-4525-9308-4112f4cbf178",
      "broadcaster_id": "141981764",
      "broadcaster_name": "TwitchDev",
      "broadcaster_login": "twitchdev",
      "title": "Will we win all the games?",
      "winning_outcome_id": "73085848-a94d-4040-9d21-2cb7a89374b7",
      "outcomes": [
        {
          "id": "73085848-a94d-4040-9d21-2cb7a89374b7",
          "title": "yes",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "BLUE"
        },
        {
          "id": "86010b2e-9764-4136-9359-fd1c9c5a8033",
          "title": "no",
          "users": 0,
          "channel_points": 0,
          "top_predictors": null,
          "color": "PINK"
        }
      ],
      "prediction_window": 120,
      "status": "RESOLVED",
      "created_at": "2021-04-28T21:48:19.480371331Z",
      "ended_at": "2021-04-28T21:54:24.026833954Z",
      "locked_at": "2021-04-28T21:48:34.636685705Z"
    }
  ]
}