{
"option_id": "0"
}
{
"status": "success",
"data": {
"sponsored_poll_id": 123,
"question": "What kind of playlist are you making?",
"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 }
]
}
}
{
"detail": "Invalid poll option"
}
v1 (deprecated)
Poll Tracking (v1)
Submit sponsored poll votes and retrieve signed aggregate results for direct API integrations.
POST
/
api
/
v1
/
tracking
/
sponsored-polls
/
vote
{
"option_id": "0"
}
{
"status": "success",
"data": {
"sponsored_poll_id": 123,
"question": "What kind of playlist are you making?",
"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 }
]
}
}
{
"detail": "Invalid poll option"
}
Sponsored poll bid responses include signed
Submit a user’s selected poll option. The vote is recorded and the endpoint returns the current lifetime aggregate results for the poll.
Retrieve current aggregate results without recording a vote. Use this endpoint to refresh percentages after rendering, or when the user returns to an already-voted poll.
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?token=...
Request
string
required
Signed token from the poll creative’s
vote_url. It is already present in the vote_url query string — POST to that URL exactly as returned. The token must be in the query string; it is not read from the request body.string
required
Selected option identifier from the poll creative’s
options[].id.{
"option_id": "0"
}
Response
The response is wrapped in astatus / data envelope. data holds the current aggregate results.
{
"status": "success",
"data": {
"sponsored_poll_id": 123,
"question": "What kind of playlist are you making?",
"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 }
]
}
}
{
"detail": "Invalid poll option"
}
string
Always
"success" for a recorded (or deduplicated) vote.object
Current aggregate poll results.
Show data properties
Show data properties
integer
Poll identifier.
string
Poll question text.
integer
Lifetime vote count for the poll.
Duplicate Votes
Each signed poll token records at most one vote for its bid/impression. A duplicate vote attempt does not increment the aggregate counts and is not an error — the endpoint returns200 with the current aggregate results, exactly like a first vote. There is no separate duplicate-vote status code, so clients do not need special handling; the returned data is always safe to render.
Results
GET /api/v1/tracking/sponsored-polls/results?token=...
Query Parameters
string
required
Signed token from the poll creative’s
results_url.Response
Samestatus / data envelope as the vote endpoint.
{
"status": "success",
"data": {
"sponsored_poll_id": 123,
"question": "What kind of playlist are you making?",
"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 }
]
}
}
string
Always
"success".object
Current aggregate poll results —
sponsored_poll_id, question, total_votes, and an options array of id / text / votes / percentage rows.Error Handling
Errors use the standard FastAPI shape — a singledetail string:
{
"detail": "Invalid poll option"
}
| Status Code | Scenario | detail | Client Behavior |
|---|---|---|---|
400 Bad Request | option_id does not match one of the poll options | Invalid poll option | Keep the poll visible and let the user choose a valid option |
404 Not Found | Token is malformed, expired, or not valid for this poll | Link expired or not found | Do not retry with the same token; request a fresh poll creative |
422 Unprocessable Entity | Required token query parameter or option_id body field is missing | FastAPI validation detail | Fix the request; this indicates a client integration bug |
500 Internal Server Error | Tracking service failed unexpectedly | Internal Server Error | Continue without blocking the chat experience |
The
422 response body uses FastAPI’s validation format (detail is an array of field errors), not a single string.Rendering Flow
- Render the poll question and option buttons from the bid response.
- Fire the impression pixel — extract the
view_urlquery parameter fromcta_url(or use the top-levelview_urlfield when the poll has nocta_url) and request it when the poll becomes visible. - When the user selects an option, POST
option_idtovote_url. - Replace the option buttons with the returned percentages and total vote count (read from the
dataobject). - If
cta_urlis present, reveal the advertiser CTA after the vote. - Use
results_urlto refresh percentages without recording another vote.