> For the complete documentation index, see [llms.txt](https://docs.zigpoll.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigpoll.com/web-api.md). # Web API Interact with your survey data using our api service The Zigpoll REST API lets you manage surveys, questions, responses, participants, translations, and webhooks programmatically. * **Base URL:** `https://v1.zigpoll.com` (not `api.zigpoll.com`) * **Authentication:** send your [API key](/integrations/api-key.md) in the `Authorization` header. The key on its own and `Bearer ` both work. * **Plan:** API access requires a **Premium** plan or higher. * **Roles:** your key carries your team role — Read only keys can't write, and webhook/integration endpoints require an API key from an **Owner**, **Admin**, or **Billing Admin**. ### Plan errors A request for an account whose plan doesn't include API access returns HTTP `403` with: ```json { "error": "This account's plan does not include API access. Please upgrade to the Premium plan or higher." } ``` Listing surveys without an `accountId` skips accounts that don't have API access. If none of your accounts has it, you get: ```json { "error": "None of your accounts are on a plan with API access. Please upgrade to the Premium plan or higher." } ``` Upgrade under **Settings → Plans & Limits**, or use a key from a login that belongs to an account on an eligible plan. ### What you can do * **Surveys & questions** — create, update, list, and duplicate surveys; manage and reorder questions (every question type is supported, including matrix, autocomplete, and phone capture); attach action logic. * **Responses & participants** — list responses, response summaries, and participants; export data. * **Translations** — read and update per-language survey translations. * **Webhooks** — create, list, and delete [signed webhooks](/integrations/webhooks.md) (requires an API key from an **Owner**, **Admin**, or **Billing Admin**; the signing secret is returned only once, on create). * **Counters** — every survey and account exposes the three counters: responses (`surveyResponseCount`, the metered unit — one per participant taking a survey), answers (`submissionCount`, one per question answered), and write-ins (`responseCount`). See [How we calculate responses](/subscription-plans/how-we-calculate-responses.md). ### Pagination and incremental sync List endpoints such as `/responses` and `/participants` are cursor-paginated: * `limit` sets the page size. The default is 50 and the maximum is 5,000. * The response includes the last record's `_id`. Pass it back as `startCursor` to fetch the next page, and stop when a page comes back short. * `/responses` returns newest first by default. Pass `order=oldest` to walk forward from the earliest response, with `startCursor` continuing in the same direction. * `createdAfter` and `createdBefore` take JavaScript timestamps in milliseconds (for example `1760000000000`) and return records created on or after, or on or before, that time. For an incremental sync, store the timestamp of your last run and request `createdAfter` with that value on the next one. There is no `updatedAfter` filter: a response is written once and does not change afterwards, unless you edit or delete it in the dashboard. ### Rate limits Requests are limited per IP address to **420 per minute**, roughly seven per second. Above that the API answers HTTP `429` and includes the standard `RateLimit` and `RateLimit-Policy` headers so a client can see how many requests remain in the window and when it resets. Back off until the window resets and retry; a steady client that stays under about six requests a second is never limited. Bulk exports should use a large `limit` rather than many small pages. ### Full reference Every endpoint, schema, and example is in the official API reference: {% hint style="info" %} Looking for the in-browser widget API (`window.Zigpoll.*`) instead? See the [Javascript API](/javascript-api.md). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.zigpoll.com/web-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.