Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thrads.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Sponsored Poll Tracking

Sponsored poll bid responses include signed vote_url and results_url values. Use those URLs exactly as returned by the bid response. The signed token authorizes access to a rendered poll instance and keeps clients from voting against or reading raw poll IDs.
Voting records poll engagement only. It does not redirect to the advertiser. If the poll response includes cta_url, show that CTA after voting and use it for advertiser click-throughs.

​
Vote

POST /api/v1/tracking/sponsored-polls/vote
Submit a user’s selected poll option. A valid vote records engagement and returns lifetime aggregate results for the poll.

​
Request

​
token
string
Signed token from the poll creative’s vote_url. If the token is already present in the vote_url query string, post to that returned URL and include only option_id in the JSON body.
​
option_id
string
required
Selected option identifier from the poll creative’s options[].id.
{
  "token": "signed-token",
  "option_id": "0"
}

​
Response

{
  "sponsored_poll_id": 123,
  "selected_option_id": "0",
  "total_votes": 42,
  "options": [
    { "id": "0", "text": "Wedding", "votes": 21, "percentage": 50 },
    { "id": "1", "text": "Study", "votes": 14, "percentage": 33.3 },
    { "id": "2", "text": "Workout", "votes": 7, "percentage": 16.7 }
  ]
}
​
sponsored_poll_id
integer
Poll identifier.
​
selected_option_id
string
Option ID submitted by the user.
​
total_votes
integer
Lifetime vote count for the poll.
​
options
array
Lifetime aggregate result rows for each option.

​
Duplicate Votes

Each signed poll token can record at most one vote for its bid/impression. Duplicate vote attempts are rejected and must not increment aggregate counts. If you need to refresh percentages after a duplicate attempt, call the poll’s results_url.

​
Results

GET /api/v1/tracking/sponsored-polls/results?token=...
Retrieve current aggregate results without recording a vote. Use this endpoint to refresh percentages after rendering, after a duplicate vote error, or when the user returns to an already-voted poll.

​
Query Parameters

​
token
string
required
Signed token from the poll creative’s results_url.

​
Response

{
  "sponsored_poll_id": 123,
  "total_votes": 42,
  "options": [
    { "id": "0", "text": "Wedding", "votes": 21, "percentage": 50 },
    { "id": "1", "text": "Study", "votes": 14, "percentage": 33.3 },
    { "id": "2", "text": "Workout", "votes": 7, "percentage": 16.7 }
  ]
}
​
sponsored_poll_id
integer
Poll identifier.
​
total_votes
integer
Lifetime vote count for the poll.
​
options
array
Lifetime aggregate result rows for each option, including id, text, votes, and percentage.

​
Error Handling

Status CodeCodeScenarioClient Behavior
400 Bad Requestmissing_tokenNo signed token was providedDo not render results; request a fresh poll creative
400 Bad Requestinvalid_optionoption_id does not match one of the poll optionsKeep the poll visible and let the user choose a valid option
401 Unauthorizedinvalid_tokenToken is malformed, expired, or not valid for this pollDo not retry with the same token; request a fresh poll creative
409 Conflictduplicate_voteToken already recorded a vote for this bid/impressionDo not submit another vote; call results_url to refresh aggregate results
500 Internal Server Errorserver_errorTracking service failed unexpectedlyContinue without blocking the chat experience
Error responses use this shape: 
{
  "error": {
    "code": "invalid_option",
    "message": "Option id is not valid for this poll."
  }
}

​
Rendering Flow

  1. Render the poll question and option buttons from the bid response.
  2. Fire or load view_url according to your normal view tracking behavior.
  3. When the user selects an option, submit option_id to vote_url.
  4. Replace option buttons with returned percentages and total vote count.
  5. If cta_url is present, reveal the advertiser CTA after the vote.
  6. Use results_url to refresh percentages without recording another vote.