---
title: "Mind Polling API"
description: "The API guide: every operation, the conventions, and reading results as of a past moment."
canonical: https://mindpolling.com/docs/api.md
---

# Mind Polling API

Poll AI models the way pollsters poll people. Base URL: https://mindpolling.com/api/v1. OpenAPI 3.1: https://mindpolling.com/openapi.json. Index: https://mindpolling.com/api. The same operations are MCP tools at https://mindpolling.com/mcp, named by their operation id.

## In five lines

1. Public polls need no key to find and read: `GET https://mindpolling.com/api/v1/polls`, then `GET .../polls/{id}/results`. Results as of a past moment (`as_of`, `first_release`) and the change feed need a free key with only the read scope, which spends nothing. Every raw answer (`list_calls`) is its poll's owner's alone: the results quote a sample reply per question.
2. For your own polls, the account holder makes a key at https://mindpolling.com/app/settings/api and you send it as `Authorization: Bearer mp_live_...`. Start with `GET https://mindpolling.com/api/v1/me`.
3. `create_poll` is free. `estimate_poll` says what running it costs. `run_poll_now` and `start_poll` spend the balance and must carry `max_cost_usd`; confirm it with the account holder.
4. Follow a run with `get_live_run`, or be told: `list_changes` (poll it) or `create_webhook` (pushed, signed).
5. Errors are `{error, code, suggestion, next_steps}`: a sentence, a stable code, what to change, and calls to make. Branch on `code`.

## Point in time

Results can change after they are first published: a newer parser can re-read stored answers. Every point and every call carries `available_at`, when this reader could first have read it (for a stranger, the later of the run finishing and the poll being public). `?as_of=` returns results exactly as they stood at that moment, with no later run and no later re-reading; `?first_release=true` returns every answer as first published. A reading marked `history_complete: false` replaced an earlier one that was never kept (before 2026-11-04). Order backtests by `available_at`.

Answers from models with web search carry `read_market`: whether the search read a Kalshi or Polymarket page. If you compare the models to a market's price, consider leaving those out: they were partly reading the price.

## Conventions

- JSON, RFC 3339 UTC times, money in micro-USD integers (fields ending `_micro`; 1,000,000 is $1).
- Ids are opaque: never parse them. Lists are `{data, next_cursor, has_more}`; pass `next_cursor` back unchanged.
- Every POST, PUT and DELETE honours `Idempotency-Key`: a retry with the same key returns the first answer.
- Rate limits: 120 requests a minute per address without a key; 600 reads and 60 writes a minute per key. Every answer carries `RateLimit` and `RateLimit-Policy`; a 429 carries `Retry-After`.
- Public poll data is CC BY 4.0: credit "Mind Polling" and the poll's author.

## Versions and deprecation

The version is in every address (`/api/v1`). Within v1, fields only grow; none is removed or renamed. A change that would break a client is a new version beside v1. Deprecation policy: a version being retired is announced on https://mindpolling.com/developers and keeps answering for at least 6 months, and for that time each answer carries a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with the date it stops. No version is deprecated today.

## Operations

### Account

#### `GET /api/v1/me` (get_me)

Check a key: whose it is, the account's balance, the key's scopes, mode and monthly allowance with what it has committed this month, the rate limits, and every operation this key cannot call with the reason and the remedy. Call this first with a new key.

A key.

#### `POST /api/v1/me/key/rotate` (rotate_key)

Replace the secret of the key making this request, keeping its name, scopes, allowance and history. The new key is in the response, shown once; the old one stops working immediately. Use it when a key may have leaked.

A key.

#### `DELETE /api/v1/me/key` (revoke_key)

Revoke the key making this request. It stops working at once and cannot be restored; polls it started stop at their next run. Use it when a key has leaked and you do not need a replacement.

A key.

### Polls

#### `GET /api/v1/polls` (list_polls)

Every public poll, latest run first, filtered and sorted as the directory at /polls is: by topic (a topic's slug), status, model, lab and search, sorted by latest run, newest, most answers or ending soon. With a key that has the read scope, mine=true lists your own polls instead (a test key lists test polls only; the filters apply to public polls). Use updated_since to fetch only polls that changed, then get_results for each.

No key for public polls; a key with read for your own.

#### `GET /api/v1/polls/{id}` (get_poll)

A poll's settings and every version: the questions and their wordings exactly as asked, the models, samples and search depth, plus any prediction markets associated with it. Accepts the poll's id or its public address (slug).

No key for public polls; a key with read for your own.

#### `POST /api/v1/polls` (create_poll)

Create a poll from a definition: questions and their wordings, the models to ask (provider and model from list_models), samples per cell, search depth, schedule and dates. It is saved as a draft and costs nothing; call estimate_poll for its cost, then start_poll or run_poll_now. A test key makes a test poll, which runs on a stub model and charges nothing. Send an Idempotency-Key so a retry cannot make two polls.

A key with write.

#### `PUT /api/v1/polls/{id}` (update_poll)

Replace a poll's definition with a new one. Before its first run the version is edited in place; once a version has run it is locked and a new version is made, so results always say what was asked. Send the whole definition, as create_poll takes it.

A key with write.

#### `GET /api/v1/polls/{id}/estimate` (estimate_poll)

What a poll will cost, from the same prices the worker charges by: one run's typical and 95th-percentile charge, what a run holds from the balance while it runs, and what starting the poll commits (hold per run times the runs left before its end date, or a month of runs when it has none). Show this to the account holder before start_poll or run_poll_now.

A key with read.

### Results

#### `GET /api/v1/polls/{id}/results` (get_results)

A poll's results. For choice and scale questions each answer's share per model per run, with its Wilson 95% interval; for number and scale questions each model's mean with its 95% interval. Every point carries available_at, when this reader could first have seen it. as_of reads the results exactly as they stood at a past moment (no later run and no later re-reading of an answer), and first_release=true reads every answer as first published; both need a free key (the historical reads are what a backtest pulls, and a key says who is pulling). Versions are continued onto the latest unless version is given.

No key for public polls; a key with read for your own.

#### `GET /api/v1/polls/{id}/runs` (list_runs)

A poll's runs, newest first: when each was due, started and finished, its status and counts, and available_at, when this reader could first have read it. A stranger sees only runs that have become available; the owner also sees queued and running ones, and charges.

No key for public polls; a key with read for your own.

#### `GET /api/v1/polls/{id}/calls` (list_calls)

Every call behind one of your polls' results, oldest first: the prompt and system prompt exactly as sent, every setting, the raw reply, how it was read, which model answered, tokens and charges, and read_market (whether its search read a prediction market). Filter by run. as_of reads each answer as it was read then. Only the poll's owner reads its calls, public or not: a public poll's readers get its results (get_results), which quote a sample reply per question.

A key with read.

### Models

#### `GET /api/v1/models` (list_models)

Every model you can put in a poll's panel right now: its provider and id (what create_poll's panel takes), name, lab, the search depths it is offered at, a typical answer's charge, and its last 30 days of cut-off and error rates. A model is offered only after it has been measured.

No key.

### Places

#### `GET /api/v1/places` (search_places)

Up to five places from Google Places whose names match q: countries, states and provinces, counties, cities and ZIP or postal codes, never an address or a business. Each has an id and its text; read the one you want with get_place, and put the result in the wording's place.

A key with read.

#### `GET /api/v1/places/{id}` (get_place)

Read one place from Google Places by its id, in the shape a wording's place takes in create_poll and update_poll: its name, kind (country, region, county, city or postal_code) and ISO country and region codes. Any other place, such as an address or a business, is refused. Models never see a wording's place; it is there so results can be shown by place.

A key with read.

### Runs

#### `POST /api/v1/polls/{id}/start` (start_poll)

Start a draft or paused poll on its schedule. Each run spends the account's balance, so the request must carry max_cost_usd, the most it may commit (estimate_poll gives the figure, and a refusal says the exact amount). Refused with 402 if the balance cannot cover it and 409 if this key's monthly allowance cannot; nothing is spent by a refusal. Confirm the cost with the account holder first.

A key with run. **Spends the account's balance.**

#### `POST /api/v1/polls/{id}/run` (run_poll_now)

Queue one run of a poll now, whatever its schedule. It asks every wording, or with share=true the next part of the poll's rotation at its sample_percent, exactly as a scheduled run would. It spends the account's balance, so the request must carry max_cost_usd (estimate_poll's run_now.hold_micro). Follow it with get_live_run, then read get_results once it settles. Refused with 409 if a run is already in progress.

A key with run. **Spends the account's balance.**

#### `POST /api/v1/polls/{id}/pause` (pause_poll)

Pause an active poll: no further runs start until it is started again. A run already in progress finishes. Needs only the write scope, since pausing stops spending.

A key with write.

#### `GET /api/v1/polls/{id}/status` (get_live_run)

The run in progress, if any: how many answers are done of how many, each model's cells as they settle, and outcome counts; plus the poll's status, when it next runs, and the last run that settled. Poll this every few seconds while a run is active; when last_settled changes, read get_results.

A key with read.

### Changes

#### `GET /api/v1/changes` (list_changes)

The change feed: every settled run, every poll made public or private, every new version and every revision of published answers, oldest first, after a cursor. Needs a free key with read: public polls' changes by default, and mine=true for your own polls'. Keep next_cursor and ask again later, adding a random minute so every client does not ask at once; or register a webhook to be told.

A key with read.

#### `POST /api/v1/webhooks` (create_webhook)

Register an https URL to receive events as Standard Webhooks: a POST with webhook-id, webhook-timestamp and webhook-signature (v1, HMAC-SHA256 of id.timestamp.body with the secret returned here, once). scope mine sends your own polls' events, public every public poll's; poll_id narrows it to one poll. Only events after it is made are sent. Answer 2xx to acknowledge; failures are retried for about three days, and 410 stops deliveries.

A key with read.

#### `GET /api/v1/webhooks` (list_webhooks)

Your webhook endpoints with their scope, events and whether each is disabled, and why. A disabled endpoint receives nothing; delete it and make another once the receiver works.

A key with read.

#### `DELETE /api/v1/webhooks/{id}` (delete_webhook)

Delete a webhook endpoint: nothing more is sent to it, including retries in progress.

A key with read.

## Webhooks

`create_webhook` registers an https URL. Deliveries follow Standard Webhooks: headers `webhook-id`, `webhook-timestamp` and `webhook-signature` (`v1,` then the base64 HMAC-SHA256 of `id.timestamp.body`, keyed by the base64 part of the `whsec_` secret returned once). Event types: `run.settled`, `poll.published`, `poll.unpublished`, `poll.versioned`, `results.revised`. The payload is thin, `{id, type, timestamp, data}` with links to read the rest. Answer 2xx; failures retry for about three days, then the endpoint is disabled, and 410 disables it at once. Reject a delivery whose timestamp is more than five minutes old.
