> ## 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 a poll > Retrieves a poll by ID with its options, settings, organizer and `participantCount`. The poll must belong to the space associated with the API key. Compare `updatedAt` between reads to notice changes. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/polls/{pollId} 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}: get: tags: - Polls summary: Get a poll description: >- Retrieves a poll by ID with its options, settings, organizer and `participantCount`. The poll must belong to the space associated with the API key. Compare `updatedAt` between reads to notice changes. operationId: getV1PollsByPollId parameters: - schema: type: string in: path name: pollId required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PollResponse' '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: PollResponse: type: object properties: data: $ref: '#/components/schemas/Poll' 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 Poll: type: object properties: id: type: string example: Xk3pQ9vLm2Ab title: type: string example: Team sync description: anyOf: - type: string - type: 'null' example: Pick a time that works for everyone location: anyOf: - type: string - type: 'null' example: Zoom timeZone: anyOf: - type: string - type: 'null' example: Europe/London status: $ref: '#/components/schemas/PollStatus' kind: $ref: '#/components/schemas/PollKind' createdAt: type: string format: date-time example: '2025-01-10T12:00:00.000Z' updatedAt: type: string format: date-time description: >- When the poll was last modified. Changes when the poll's details, settings or status change. example: '2025-01-12T08:30:00.000Z' organizer: anyOf: - $ref: '#/components/schemas/PollOrganizer' - type: 'null' description: >- The space member the poll belongs to. `null` when the organizer's account no longer exists. requireEmail: type: boolean description: Whether participants must provide their email address example: false hideParticipants: type: boolean description: Whether participant names are hidden from other participants example: false hideScores: type: boolean description: Whether vote counts are hidden from participants example: false disableComments: type: boolean description: Whether the comments section is disabled example: true allowTentativeVotes: type: boolean description: Whether participants may cast the tentative "if need be" vote example: true participantCount: type: integer minimum: 0 maximum: 9007199254740991 description: Number of participants who have responded to the poll example: 3 options: type: array items: $ref: '#/components/schemas/PollOption' adminUrl: type: string example: https://app.rallly.co/poll/Xk3pQ9vLm2Ab inviteUrl: type: string example: https://rallly.co/invite/Xk3pQ9vLm2Ab required: - id - title - description - location - timeZone - status - kind - createdAt - updatedAt - organizer - requireEmail - hideParticipants - hideScores - disableComments - allowTentativeVotes - participantCount - options - adminUrl - inviteUrl PollStatus: type: string enum: - open - closed - scheduled - canceled 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 PollOrganizer: type: object properties: id: type: string example: cm3f7d1qa0000t2k9c6b8h4jr name: type: string example: John Doe email: type: string format: email example: organizer@example.com image: anyOf: - type: string - type: 'null' example: https://cdn.rallly.co/avatars/cm3f7d1qa0000t2k9c6b8h4jr.jpg required: - id - name - email - image PollOption: anyOf: - $ref: '#/components/schemas/DateOption' - $ref: '#/components/schemas/TimeOption' description: >- A poll option. The shape follows the poll's `kind`: a `DateOption` for `date` polls, a `TimeOption` for `time` polls. DateOption: 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' required: - id - date description: 'An all-day option. Only present in polls with `kind: date`.' TimeOption: 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 required: - id - startTime - duration description: 'A time slot. Only present in polls with `kind: time`.' securitySchemes: bearerAuth: type: http scheme: bearer ````