> ## Documentation Index > Fetch the complete documentation index at: https://support.rallly.co/llms.txt > Use this file to discover all available pages before exploring further. # Get poll results > Retrieves aggregated voting results for a poll: vote counts per option without individual participant data. Use `GET /polls/:pollId/participants` to list who responded. `votes` lists every vote type the poll offers with its count, zero included. `score` is an opaque ranking value: sort by it to order options from best to worst, and use `isTopChoice` or `highScore` to find the leading options. Its formula is not part of the contract, so do not decode it, compare it across polls or threshold on it. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/polls/{pollId}/results openapi: 3.1.0 info: title: Rallly API description: >- ## Versioning `v1` is stable. Additive changes (new endpoints, new optional fields) may land on this path at any time; breaking changes only arrive under a new version prefix. ## Rate limits All endpoints share two limits per space: **60 requests per minute** and **5000 requests per day**. Both are fixed windows that open with the first request and reset when they expire. Both limits are per space, not per API key, so creating additional keys does not increase throughput. Every response from an authenticated request includes the standard `RateLimit-*` headers. Responses sent before the limiter runs (`401`, `403`, and the maintenance `503`) do not. `RateLimit-Policy` lists both limits; `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` describe whichever limit is closest to being exhausted. When either limit is exceeded the API responds with `429 Too Many Requests`, a `RATE_LIMIT_EXCEEDED` error body, and a `Retry-After` header indicating how many seconds to wait before retrying. If the rate limit store cannot be reached the API fails closed and responds with `503 Service Unavailable`, a `SERVICE_UNAVAILABLE` error body, and a `Retry-After` header. ## Dates and times Every poll has a `kind`. A `date` poll offers calendar days: each option carries a `date` in `YYYY-MM-DD` format, which is a floating date with no time component and no timezone, so never convert it through a timezone. A `time` poll offers time slots: each option carries a `startTime` as an ISO 8601 instant in UTC and a `duration` in minutes; convert `startTime` into the poll's `timeZone` (or the viewer's) for display. Timestamps such as `createdAt` and `updatedAt` are always ISO 8601 instants in UTC. ## Request bodies Request bodies are validated strictly: a field that is not part of the documented schema is rejected with `VALIDATION_ERROR` rather than ignored, so a misspelt setting never silently falls back to its default. ## Enums Vote types are an open set. The built-in values are `yes`, `ifNeedBe` and `no`; new types may be added without a version change, so clients must tolerate values they do not recognise. `status` and `kind` are closed sets. ## Lists List endpoints return the items in `data`. `GET /polls` is paginated: it returns a `nextCursor` beside `data`; pass it as the `cursor` query parameter to fetch the next page, and it is `null` on the last page. `GET /polls/:pollId/participants` returns every participant in one response. ## Errors Every failure is `application/json` with the shape `{ "error": { "code", "message" } }`. `code` is stable and safe to branch on; `message` is human-readable and may change. `VALIDATION_ERROR` messages name each offending field. | Status | Code | When | | --- | --- | --- | | 400 | `VALIDATION_ERROR` | The body or query string did not match the schema, contained an unknown field, or the body was not valid JSON | | 400 | `INVALID_AUTHORIZATION_HEADER` | The `Authorization` header is not `Bearer ` | | 400 | `ORGANIZER_NOT_MEMBER` | The organizer email is not a member of the space | | 400 | `TOO_MANY_OPTIONS` | More than the maximum number of poll options | | 400 | `INAPPROPRIATE_CONTENT` | The title, description or location was flagged by content moderation | | 401 | `UNAUTHORIZED` | The API key is missing, invalid, expired or revoked, or its owner is banned | | 403 | `SPACE_NOT_PRO` | The space behind the key has no Pro subscription | | 404 | `NOT_FOUND` | No route matches the method and path | | 404 | `POLL_NOT_FOUND` | The poll does not exist or belongs to another space | | 429 | `RATE_LIMIT_EXCEEDED` | A rate limit window is exhausted | | 503 | `SERVICE_UNAVAILABLE` | Maintenance, or the rate limit store cannot be reached | | 500 | `INTERNAL_ERROR` | Unexpected failure; the request id is logged | version: 1.0.0 servers: - url: https://api.rallly.co security: [] paths: /v1/polls/{pollId}/results: get: tags: - Polls summary: Get poll results description: >- Retrieves aggregated voting results for a poll: vote counts per option without individual participant data. Use `GET /polls/:pollId/participants` to list who responded. `votes` lists every vote type the poll offers with its count, zero included. `score` is an opaque ranking value: sort by it to order options from best to worst, and use `isTopChoice` or `highScore` to find the leading options. Its formula is not part of the contract, so do not decode it, compare it across polls or threshold on it. operationId: getV1PollsByPollIdResults parameters: - schema: type: string in: path name: pollId required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetPollResultsResponse' '401': description: >- The API key is missing, invalid, expired or revoked, or its owner is banned. Includes a `WWW-Authenticate` header. headers: WWW-Authenticate: description: The bearer challenge, per RFC 6750. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The space associated with the API key does not have a Pro subscription content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Poll not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying. headers: Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers. headers: Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: GetPollResultsResponse: type: object properties: data: type: object properties: pollId: type: string example: Xk3pQ9vLm2Ab kind: $ref: '#/components/schemas/PollKind' status: $ref: '#/components/schemas/PollStatus' description: >- Current poll status. Polls close automatically when all options are in the past. example: open participantCount: type: integer minimum: 0 maximum: 9007199254740991 description: Total number of participants example: 8 options: type: array items: $ref: '#/components/schemas/OptionResult' highScore: type: integer minimum: 0 maximum: 9007199254740991 description: >- The highest `score` among the options. Opaque like `score`: use it to identify the leading options, not as a measurement. example: 5004 required: - pollId - kind - status - participantCount - options - highScore required: - data ErrorResponse: type: object properties: error: type: object properties: code: type: string description: >- Machine-readable error code. The full list is in the API description. example: VALIDATION_ERROR message: type: string description: >- Human-readable explanation. For `VALIDATION_ERROR` it names each offending field, e.g. `title: Invalid input: expected string, received undefined; dates.0: Invalid ISO date`. example: 'title: Invalid input: expected string, received undefined' required: - code - message required: - error PollKind: type: string enum: - date - time description: >- Whether the poll offers calendar dates (`date`) or time slots (`time`). Determines which option shape the poll uses: every option in a `date` poll has a `date`, every option in a `time` poll has a `startTime` and `duration`. example: time PollStatus: type: string enum: - open - closed - scheduled - canceled OptionResult: anyOf: - $ref: '#/components/schemas/DateOptionResult' - $ref: '#/components/schemas/TimeOptionResult' description: >- Results for one option. The shape follows the poll's `kind`: a `DateOptionResult` for `date` polls, a `TimeOptionResult` for `time` polls. DateOptionResult: type: object properties: id: type: string example: cm5h8x2k40000q9l4f7e2d3an date: type: string format: date description: >- Calendar date in YYYY-MM-DD format. All-day options are floating dates with no time component and no timezone. example: '2025-01-15' votes: type: array items: $ref: '#/components/schemas/VoteCount' description: >- One entry per vote type the poll offers, in display order, always present with `count: 0` when nobody chose it. score: type: integer minimum: 0 maximum: 9007199254740991 description: >- Opaque ranking value: higher is better. Only comparable between options in the same response. The formula is not part of the contract and may change; do not decode it into vote counts, compare it across polls or threshold on it. Use `votes` for counts. example: 5004 isTopChoice: type: boolean description: >- Whether this option has the highest `score` in the poll. Several options share the flag when they tie. Always `false` when nobody has voted. example: true required: - id - date - votes - score - isTopChoice description: 'Results for an all-day option. Only present in polls with `kind: date`.' TimeOptionResult: type: object properties: id: type: string example: cm5h8x2k40000q9l4f7e2d3an startTime: type: string format: date-time description: Start of the slot as an ISO 8601 instant in UTC. example: '2025-01-15T09:00:00.000Z' duration: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 description: Duration in minutes. example: 30 votes: type: array items: $ref: '#/components/schemas/VoteCount' description: >- One entry per vote type the poll offers, in display order, always present with `count: 0` when nobody chose it. score: type: integer minimum: 0 maximum: 9007199254740991 description: >- Opaque ranking value: higher is better. Only comparable between options in the same response. The formula is not part of the contract and may change; do not decode it into vote counts, compare it across polls or threshold on it. Use `votes` for counts. example: 5004 isTopChoice: type: boolean description: >- Whether this option has the highest `score` in the poll. Several options share the flag when they tie. Always `false` when nobody has voted. example: true required: - id - startTime - duration - votes - score - isTopChoice description: 'Results for a time slot. Only present in polls with `kind: time`.' VoteCount: type: object properties: type: $ref: '#/components/schemas/VoteType' count: type: integer minimum: 0 maximum: 9007199254740991 description: Number of participants who gave this answer. example: 3 required: - type - count VoteType: type: string description: >- A participant's answer for an option. The built-in types are `yes` (available), `ifNeedBe` (available if needed) and `no` (unavailable). New types may be added without a version change, so treat unknown values as a vote of an unfamiliar type rather than an error. example: 'yes' securitySchemes: bearerAuth: type: http scheme: bearer ````