Polls of AI models: read public results with no key; create and run your own with an API key.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer mp_live_... for your own polls; public polls need none.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
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. (POST /api/v1/polls)
1 to 30 models to ask, each once.
The poll's title.
once, daily or weekly.
1 to 50 questions, in order.
How many times each model is asked each wording per run, 1 to 50: more samples, narrower ranges.
realtime (the default), or batch: scheduled runs ask the models that can be batched (Anthropic) through the providers' batch APIs, cheaper, with answers arriving up to 2 hours after the run starts; run_poll_now is always real time. OpenAI and Google models are asked at their flex tier, the same price, in real time, either way. Left out: unchanged.
The last day it runs, at most 90 days after start_date.
The time of day it runs, HH:MM in time_zone; null runs from the moment it is started.
The IANA time zone of its dates and run time.
A name for the composite of the poll's Better-Worse index questions, such as "AI Economy Index"; empty for "Composite Better-Worse index". Shown only when two or more questions have the index.
The first day it runs, YYYY-MM-DD in time_zone; needs run_time.
Why this version differs from the last, kept in the poll's history.
What the poll is for, or empty.
Weekly polls: the day it runs, 0 = Sunday.
Searches allowed per answer, for every model with search on.
The earlier version this one was started from, or null.
The system prompt every wording is asked under unless it has its own; empty for none.
The share of the poll's wordings each scheduled run asks, 1 to 100 percent; every wording is asked once before any is asked again. Left out: unchanged (100 for a new poll). run_poll_now asks this share with share=true, every wording otherwise.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Pick your client. Values in capitals, like YOUR_TOKEN, are yours to fill in.
Run in a terminal
claude mcp add --transport http mindpolling https://mindpolling.com/mcp
Headers
Authorization (optional, not in the config above): Bearer mp_live_... for your own polls; public polls need none.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. (POST /api/v1/polls)
| Argument | Type | Description |
|---|---|---|
| panel* | array | 1 to 30 models to ask, each once. |
| title* | string | The poll's title. |
| delivery | string | realtime (the default), or batch: scheduled runs ask the models that can be batched (Anthropic) through the providers' batch APIs, cheaper, with answers arriving up to 2 hours after the run starts; run_poll_now is always real time. OpenAI and Google models are asked at their flex tier, the same price, in real time, either way. Left out: unchanged. |
| end_date | any | The last day it runs, at most 90 days after start_date. |
| run_time | any | The time of day it runs, HH:MM in time_zone; null runs from the moment it is started. |
| schedule* | string | once, daily or weekly. |
| questions* | array | 1 to 50 questions, in order. |
| time_zone | string | The IANA time zone of its dates and run time. |
| index_name | string | A name for the composite of the poll's Better-Worse index questions, such as "AI Economy Index"; empty for "Composite Better-Worse index". Shown only when two or more questions have the index. |
| start_date | any | The first day it runs, YYYY-MM-DD in time_zone; needs run_time. |
| change_note | string | Why this version differs from the last, kept in the poll's history. |
| description | string | What the poll is for, or empty. |
| run_weekday | any | Weekly polls: the day it runs, 0 = Sunday. |
| search_depth | integer | Searches allowed per answer, for every model with search on. |
| restored_from | any | The earlier version this one was started from, or null. |
| system_prompt | string | The system prompt every wording is asked under unless it has its own; empty for none. |
| sample_percent | integer | The share of the poll's wordings each scheduled run asks, 1 to 100 percent; every wording is asked once before any is asked again. Left out: unchanged (100 for a new poll). run_poll_now asks this share with share=true, every wording otherwise. |
| samples_per_cell* | integer | How many times each model is asked each wording per run, 1 to 50: more samples, narrower ranges. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"title",
"schedule",
"samples_per_cell",
"questions",
"panel"
],
"properties": {
"panel": {
"type": "array",
"items": {
"type": "object",
"required": [
"provider",
"model"
],
"properties": {
"model": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "The model id, as list_models gives it."
},
"search": {
"type": "boolean",
"default": false,
"description": "Whether the model may search the web, at the poll's search_depth. Only where list_models offers that depth."
},
"provider": {
"enum": [
"anthropic",
"openai",
"google",
"xai",
"openrouter",
"stub"
],
"type": "string",
"description": "The provider, as list_models gives it."
},
"temperature": {
"anyOf": [
{
"type": "number",
"maximum": 2,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "The temperature to send, or null for the provider's default."
},
"reasoning_effort": {
"anyOf": [
{
"type": "string",
"maxLength": 20
},
{
"type": "null"
}
],
"default": null,
"description": "The reasoning setting to send, or null for the model's lowest."
}
}
},
"maxItems": 30,
"minItems": 1,
"description": "1 to 30 models to ask, each once."
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's title."
},
"delivery": {
"enum": [
"realtime",
"batch"
],
"type": "string",
"description": "realtime (the default), or batch: scheduled runs ask the models that can be batched (Anthropic) through the providers' batch APIs, cheaper, with answers arriving up to 2 hours after the run starts; run_poll_now is always real time. OpenAI and Google models are asked at their flex tier, the same price, in real time, either way. Left out: unchanged."
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
{
"type": "null"
}
],
"default": null,
"description": "The last day it runs, at most 90 days after start_date."
},
"run_time": {
"anyOf": [
{
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
{
"type": "null"
}
],
"default": null,
"description": "The time of day it runs, HH:MM in time_zone; null runs from the moment it is started."
},
"schedule": {
"enum": [
"once",
"daily",
"weekly"
],
"type": "string",
"description": "once, daily or weekly."
},
"questions": {
"type": "array",
"items": {
"type": "object",
"required": [
"answer_type",
"variations"
],
"properties": {
"measure": {
"anyOf": [
{
"enum": [
"diffusion"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "diffusion: results also show a -100 to +100 Better-Worse index, the share answering Better less the share answering Worse (0 is balanced: as many Better as Worse answers, or all About the same). Only on a choice question whose options are exactly Better, About the same and Worse, in that order; null otherwise."
},
"options": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"default": [],
"maxItems": 12,
"description": "Choice questions: 2 to 12 options, shown in a fresh random order on every call."
},
"scale_max": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
],
"default": null,
"description": "Scale questions: the highest value, at most 20 above scale_min."
},
"scale_min": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
],
"default": null,
"description": "Scale questions: the lowest value."
},
"number_max": {
"type": [
"number",
"null"
],
"default": null,
"description": "Number questions: the highest answer accepted, or null."
},
"number_min": {
"type": [
"number",
"null"
],
"default": null,
"description": "Number questions: the lowest answer accepted, or null."
},
"variations": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "The question exactly as the model is asked it."
},
"label": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "A short name for this wording, shown beside its results."
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name",
"kind",
"country",
"region"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10,1000}$",
"description": "Google's place id."
},
"kind": {
"enum": [
"country",
"region",
"county",
"city",
"postal_code"
],
"type": "string",
"description": "country, region (a state or province), county, city, or postal_code (a ZIP or postal code, the finest)."
},
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "The place's name, as Google formats its address, such as \"Alaska, USA\"."
},
"region": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
},
{
"type": "null"
}
],
"description": "The ISO 3166-2 code of the state or province it is in, such as US-AK, or null."
},
"country": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
],
"description": "The ISO 3166-1 country code, such as US, or null."
}
},
"description": "The place this wording asks about, from Google Places. Models never see it; the wording's text names the place."
},
{
"type": "null"
}
]
},
"system_prompt": {
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
],
"description": "A system prompt for this wording alone, in place of the poll's; null or empty uses the poll's."
}
}
},
"maxItems": 100,
"minItems": 1,
"description": "1 to 100 wordings of the question; each is asked samples_per_cell times of every model."
},
"answer_type": {
"enum": [
"choice",
"scale",
"number",
"free_text"
],
"type": "string",
"description": "choice (pick one option), scale (a whole number between scale_min and scale_max), number, or free_text."
},
"number_unit": {
"type": "string",
"default": "",
"maxLength": 20,
"description": "Number questions: the unit, such as US dollars or %, or empty."
},
"scale_max_label": {
"type": "string",
"default": "",
"maxLength": 60,
"description": "Scale questions: what the highest value means."
},
"scale_min_label": {
"type": "string",
"default": "",
"maxLength": 60,
"description": "Scale questions: what the lowest value means."
}
}
},
"maxItems": 50,
"minItems": 1,
"description": "1 to 50 questions, in order."
},
"time_zone": {
"type": "string",
"default": "America/Anchorage",
"maxLength": 64,
"minLength": 1,
"description": "The IANA time zone of its dates and run time."
},
"index_name": {
"type": "string",
"default": "",
"maxLength": 80,
"description": "A name for the composite of the poll's Better-Worse index questions, such as \"AI Economy Index\"; empty for \"Composite Better-Worse index\". Shown only when two or more questions have the index."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
{
"type": "null"
}
],
"default": null,
"description": "The first day it runs, YYYY-MM-DD in time_zone; needs run_time."
},
"change_note": {
"type": "string",
"default": "",
"maxLength": 500,
"description": "Why this version differs from the last, kept in the poll's history."
},
"description": {
"type": "string",
"default": "",
"maxLength": 2000,
"description": "What the poll is for, or empty."
},
"run_weekday": {
"anyOf": [
{
"type": "integer",
"maximum": 6,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Weekly polls: the day it runs, 0 = Sunday."
},
"search_depth": {
"type": "integer",
"default": 1,
"maximum": 3,
"minimum": 1,
"description": "Searches allowed per answer, for every model with search on."
},
"restored_from": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "The earlier version this one was started from, or null."
},
"system_prompt": {
"type": "string",
"default": "",
"maxLength": 4000,
"description": "The system prompt every wording is asked under unless it has its own; empty for none."
},
"sample_percent": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "The share of the poll's wordings each scheduled run asks, 1 to 100 percent; every wording is asked once before any is asked again. Left out: unchanged (100 for a new poll). run_poll_now asks this share with share=true, every wording otherwise."
},
"samples_per_cell": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "How many times each model is asked each wording per run, 1 to 50: more samples, narrower ranges."
}
}
}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. (POST /api/v1/webhooks)
| Argument | Type | Description |
|---|---|---|
| url* | string | Your receiver's https URL. |
| scope | string | mine: your own polls. public: every public poll. |
| events | array | Which event types to send. Default: all. |
| poll_id | any | Only this poll's events. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"maxLength": 2000,
"description": "Your receiver's https URL."
},
"scope": {
"enum": [
"mine",
"public"
],
"type": "string",
"default": "mine",
"description": "mine: your own polls. public: every public poll."
},
"events": {
"type": "array",
"items": {
"enum": [
"run.settled",
"poll.published",
"poll.unpublished",
"poll.versioned",
"results.revised"
],
"type": "string"
},
"default": [
"run.settled",
"poll.published",
"poll.unpublished",
"poll.versioned",
"results.revised"
],
"minItems": 1,
"description": "Which event types to send. Default: all."
},
"poll_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
],
"default": null,
"description": "Only this poll's events."
}
}
}Delete a webhook endpoint: nothing more is sent to it, including retries in progress. (DELETE /api/v1/webhooks/{id})
| Argument | Type | Description |
|---|---|---|
| id* | string | The webhook's id. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The webhook's id."
}
}
}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. (GET /api/v1/polls/{id}/estimate)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
}
}
}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. (GET /api/v1/polls/{id}/status)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
}
}
}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. (GET /api/v1/me)
No arguments.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {}
}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. (GET /api/v1/places/{id})
| Argument | Type | Description |
|---|---|---|
| id* | string | A Google place id, from search_places. |
| session | string | Optional: one UUID you make for a search and the read that follows it, which Google bills as one session. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10,1000}$",
"description": "A Google place id, from search_places."
},
"session": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Optional: one UUID you make for a search and the read that follows it, which Google bills as one session."
}
}
}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). (GET /api/v1/polls/{id})
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
}
}
}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. (GET /api/v1/polls/{id}/results)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
| view | string | pooled adds up a question's wordings; by-wording keeps them apart. |
| as_of | string | Read as things stood at this moment (RFC 3339): only runs this reader could have seen by then, each answer as it was read then. Needs a key. |
| version | integer | One version only. Default: every version continued onto the latest. |
| first_release | string | true: each answer's first reading, as first published, rather than its latest. Needs a key. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
},
"view": {
"enum": [
"pooled",
"by-wording"
],
"type": "string",
"default": "pooled",
"description": "pooled adds up a question's wordings; by-wording keeps them apart."
},
"as_of": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Read as things stood at this moment (RFC 3339): only runs this reader could have seen by then, each answer as it was read then. Needs a key."
},
"version": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "One version only. Default: every version continued onto the latest."
},
"first_release": {
"enum": [
"true",
"false"
],
"type": "string",
"description": "true: each answer's first reading, as first published, rather than its latest. Needs a key."
}
}
}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. (GET /api/v1/polls/{id}/calls)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
| as_of | string | Read as things stood at this moment (RFC 3339): only runs this reader could have seen by then, each answer as it was read then. |
| limit | integer | Calls per page, 1 to 500. |
| cursor | string | next_cursor from the previous page, unchanged. |
| run_id | string | Only this run's calls. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
},
"as_of": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Read as things stood at this moment (RFC 3339): only runs this reader could have seen by then, each answer as it was read then."
},
"limit": {
"type": "integer",
"default": 200,
"maximum": 500,
"minimum": 1,
"description": "Calls per page, 1 to 500."
},
"cursor": {
"type": "string",
"maxLength": 500,
"description": "next_cursor from the previous page, unchanged."
},
"run_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Only this run's calls."
}
}
}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. (GET /api/v1/changes)
| Argument | Type | Description |
|---|---|---|
| mine | string | true: your own polls' changes (needs a key with read). Default: public polls'. |
| limit | integer | Events per page, 1 to 500. |
| types | string | Comma-separated event types to include. Default: all. |
| cursor | string | next_cursor from the previous page. Leave it out to start from the oldest kept event. |
| poll_id | string | Only this poll's changes. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"mine": {
"enum": [
"true",
"false"
],
"type": "string",
"description": "true: your own polls' changes (needs a key with read). Default: public polls'."
},
"limit": {
"type": "integer",
"default": 100,
"maximum": 500,
"minimum": 1,
"description": "Events per page, 1 to 500."
},
"types": {
"type": "string",
"maxLength": 200,
"description": "Comma-separated event types to include. Default: all."
},
"cursor": {
"type": "string",
"maxLength": 200,
"description": "next_cursor from the previous page. Leave it out to start from the oldest kept event."
},
"poll_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Only this poll's changes."
}
}
}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. (GET /api/v1/models)
No arguments.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {}
}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. (GET /api/v1/polls)
| Argument | Type | Description |
|---|---|---|
| q | string | Public polls: only those whose title, description, first question or topics contain every word given. |
| lab | string | Public polls: only those asking a model from this lab, such as Anthropic. |
| mine | string | true: your own polls (needs a key with read). Default: public polls. |
| sort | string | Public polls: latest run first (the default), newest published, most answers, or soonest end date (polls with none last). |
| limit | integer | Items per page, 1 to 100. |
| model | string | Public polls: only those asking this model, by its display name. |
| topic | string | Public polls: only those with this topic, by its slug (as in /polls/topics/{slug}). |
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. (GET /api/v1/polls/{id}/runs)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
| limit | integer | Items per page, 1 to 100. |
| cursor | string | next_cursor from the previous page, unchanged. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1,
"description": "Items per page, 1 to 100."
},
"cursor": {
"type": "string",
"maxLength": 500,
"description": "next_cursor from the previous page, unchanged."
}
}
}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. (GET /api/v1/webhooks)
No arguments.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {}
}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. (POST /api/v1/polls/{id}/pause)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
}
}
}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. (DELETE /api/v1/me/key)
No arguments.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {}
}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. (POST /api/v1/me/key/rotate)
No arguments.
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {}
}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. (POST /api/v1/polls/{id}/run)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
| share | boolean | true: ask the next part of the rotation at the poll's sample_percent, as a scheduled run would (estimate_poll's per_run). false: every wording (run_now). |
| max_cost_usd | number | The most, in US dollars, you agree this may commit. Required: the call is refused with the amount it needs if this is missing or too low. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
},
"share": {
"type": "boolean",
"default": false,
"description": "true: ask the next part of the rotation at the poll's sample_percent, as a scheduled run would (estimate_poll's per_run). false: every wording (run_now)."
},
"max_cost_usd": {
"type": "number",
"maximum": 100000,
"description": "The most, in US dollars, you agree this may commit. Required: the call is refused with the amount it needs if this is missing or too low.",
"exclusiveMinimum": 0
}
}
}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. (GET /api/v1/places)
| Argument | Type | Description |
|---|---|---|
| q* | string | What to look for, such as Alaska or Bethel. |
| session | string | Optional: one UUID you make for a search and the read that follows it, which Google bills as one session. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"q"
],
"properties": {
"q": {
"type": "string",
"maxLength": 100,
"minLength": 2,
"description": "What to look for, such as Alaska or Bethel."
},
"session": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Optional: one UUID you make for a search and the read that follows it, which Google bills as one session."
}
}
}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. (POST /api/v1/polls/{id}/start)
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
| max_cost_usd | number | The most, in US dollars, you agree this may commit. Required: the call is refused with the amount it needs if this is missing or too low. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
},
"max_cost_usd": {
"type": "number",
"maximum": 100000,
"description": "The most, in US dollars, you agree this may commit. Required: the call is refused with the amount it needs if this is missing or too low.",
"exclusiveMinimum": 0
}
}
}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. (PUT /api/v1/polls/{id})
| Argument | Type | Description |
|---|---|---|
| id* | string | The poll's id, or its public address (slug). |
| panel* | array | 1 to 30 models to ask, each once. |
| title* | string | The poll's title. |
| delivery | string | realtime (the default), or batch: scheduled runs ask the models that can be batched (Anthropic) through the providers' batch APIs, cheaper, with answers arriving up to 2 hours after the run starts; run_poll_now is always real time. OpenAI and Google models are asked at their flex tier, the same price, in real time, either way. Left out: unchanged. |
| end_date | any | The last day it runs, at most 90 days after start_date. |
| run_time | any | The time of day it runs, HH:MM in time_zone; null runs from the moment it is started. |
| schedule* | string | once, daily or weekly. |
| questions |
We read every tool's name, description and inputs the way the model will, looking for instructions hidden from you. A clean result means no warning signs, not a guarantee. Scanned Nov 20, 2026.
| cursor | string | next_cursor from the previous page, unchanged. |
| status | string | Public polls: running (on a schedule), stopped (ended, paused, or run once by hand), or all (the default). |
| updated_since | string | Only polls whose last run or edit is after this moment. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"q": {
"type": "string",
"maxLength": 100,
"description": "Public polls: only those whose title, description, first question or topics contain every word given."
},
"lab": {
"type": "string",
"maxLength": 100,
"description": "Public polls: only those asking a model from this lab, such as Anthropic."
},
"mine": {
"enum": [
"true",
"false"
],
"type": "string",
"description": "true: your own polls (needs a key with read). Default: public polls."
},
"sort": {
"enum": [
"latest",
"newest",
"answers",
"ending"
],
"type": "string",
"default": "latest",
"description": "Public polls: latest run first (the default), newest published, most answers, or soonest end date (polls with none last)."
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 100,
"minimum": 1,
"description": "Items per page, 1 to 100."
},
"model": {
"type": "string",
"maxLength": 100,
"description": "Public polls: only those asking this model, by its display name."
},
"topic": {
"type": "string",
"maxLength": 40,
"description": "Public polls: only those with this topic, by its slug (as in /polls/topics/{slug})."
},
"cursor": {
"type": "string",
"maxLength": 500,
"description": "next_cursor from the previous page, unchanged."
},
"status": {
"enum": [
"running",
"stopped",
"all"
],
"type": "string",
"default": "all",
"description": "Public polls: running (on a schedule), stopped (ended, paused, or run once by hand), or all (the default)."
},
"updated_since": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
"description": "Only polls whose last run or edit is after this moment."
}
}
}| array |
| 1 to 50 questions, in order. |
| time_zone | string | The IANA time zone of its dates and run time. |
| index_name | string | A name for the composite of the poll's Better-Worse index questions, such as "AI Economy Index"; empty for "Composite Better-Worse index". Shown only when two or more questions have the index. |
| start_date | any | The first day it runs, YYYY-MM-DD in time_zone; needs run_time. |
| change_note | string | Why this version differs from the last, kept in the poll's history. |
| description | string | What the poll is for, or empty. |
| run_weekday | any | Weekly polls: the day it runs, 0 = Sunday. |
| search_depth | integer | Searches allowed per answer, for every model with search on. |
| restored_from | any | The earlier version this one was started from, or null. |
| system_prompt | string | The system prompt every wording is asked under unless it has its own; empty for none. |
| sample_percent | integer | The share of the poll's wordings each scheduled run asks, 1 to 100 percent; every wording is asked once before any is asked again. Left out: unchanged (100 for a new poll). run_poll_now asks this share with share=true, every wording otherwise. |
| samples_per_cell* | integer | How many times each model is asked each wording per run, 1 to 50: more samples, narrower ranges. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id",
"title",
"schedule",
"samples_per_cell",
"questions",
"panel"
],
"properties": {
"id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's id, or its public address (slug)."
},
"panel": {
"type": "array",
"items": {
"type": "object",
"required": [
"provider",
"model"
],
"properties": {
"model": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "The model id, as list_models gives it."
},
"search": {
"type": "boolean",
"default": false,
"description": "Whether the model may search the web, at the poll's search_depth. Only where list_models offers that depth."
},
"provider": {
"enum": [
"anthropic",
"openai",
"google",
"xai",
"openrouter",
"stub"
],
"type": "string",
"description": "The provider, as list_models gives it."
},
"temperature": {
"anyOf": [
{
"type": "number",
"maximum": 2,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "The temperature to send, or null for the provider's default."
},
"reasoning_effort": {
"anyOf": [
{
"type": "string",
"maxLength": 20
},
{
"type": "null"
}
],
"default": null,
"description": "The reasoning setting to send, or null for the model's lowest."
}
}
},
"maxItems": 30,
"minItems": 1,
"description": "1 to 30 models to ask, each once."
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "The poll's title."
},
"delivery": {
"enum": [
"realtime",
"batch"
],
"type": "string",
"description": "realtime (the default), or batch: scheduled runs ask the models that can be batched (Anthropic) through the providers' batch APIs, cheaper, with answers arriving up to 2 hours after the run starts; run_poll_now is always real time. OpenAI and Google models are asked at their flex tier, the same price, in real time, either way. Left out: unchanged."
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
{
"type": "null"
}
],
"default": null,
"description": "The last day it runs, at most 90 days after start_date."
},
"run_time": {
"anyOf": [
{
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
{
"type": "null"
}
],
"default": null,
"description": "The time of day it runs, HH:MM in time_zone; null runs from the moment it is started."
},
"schedule": {
"enum": [
"once",
"daily",
"weekly"
],
"type": "string",
"description": "once, daily or weekly."
},
"questions": {
"type": "array",
"items": {
"type": "object",
"required": [
"answer_type",
"variations"
],
"properties": {
"measure": {
"anyOf": [
{
"enum": [
"diffusion"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "diffusion: results also show a -100 to +100 Better-Worse index, the share answering Better less the share answering Worse (0 is balanced: as many Better as Worse answers, or all About the same). Only on a choice question whose options are exactly Better, About the same and Worse, in that order; null otherwise."
},
"options": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"default": [],
"maxItems": 12,
"description": "Choice questions: 2 to 12 options, shown in a fresh random order on every call."
},
"scale_max": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
],
"default": null,
"description": "Scale questions: the highest value, at most 20 above scale_min."
},
"scale_min": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
{
"type": "null"
}
],
"default": null,
"description": "Scale questions: the lowest value."
},
"number_max": {
"type": [
"number",
"null"
],
"default": null,
"description": "Number questions: the highest answer accepted, or null."
},
"number_min": {
"type": [
"number",
"null"
],
"default": null,
"description": "Number questions: the lowest answer accepted, or null."
},
"variations": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "The question exactly as the model is asked it."
},
"label": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "A short name for this wording, shown beside its results."
},
"place": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"name",
"kind",
"country",
"region"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10,1000}$",
"description": "Google's place id."
},
"kind": {
"enum": [
"country",
"region",
"county",
"city",
"postal_code"
],
"type": "string",
"description": "country, region (a state or province), county, city, or postal_code (a ZIP or postal code, the finest)."
},
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "The place's name, as Google formats its address, such as \"Alaska, USA\"."
},
"region": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$"
},
{
"type": "null"
}
],
"description": "The ISO 3166-2 code of the state or province it is in, such as US-AK, or null."
},
"country": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Z]{2}$"
},
{
"type": "null"
}
],
"description": "The ISO 3166-1 country code, such as US, or null."
}
},
"description": "The place this wording asks about, from Google Places. Models never see it; the wording's text names the place."
},
{
"type": "null"
}
]
},
"system_prompt": {
"anyOf": [
{
"type": "string",
"maxLength": 4000
},
{
"type": "null"
}
],
"description": "A system prompt for this wording alone, in place of the poll's; null or empty uses the poll's."
}
}
},
"maxItems": 100,
"minItems": 1,
"description": "1 to 100 wordings of the question; each is asked samples_per_cell times of every model."
},
"answer_type": {
"enum": [
"choice",
"scale",
"number",
"free_text"
],
"type": "string",
"description": "choice (pick one option), scale (a whole number between scale_min and scale_max), number, or free_text."
},
"number_unit": {
"type": "string",
"default": "",
"maxLength": 20,
"description": "Number questions: the unit, such as US dollars or %, or empty."
},
"scale_max_label": {
"type": "string",
"default": "",
"maxLength": 60,
"description": "Scale questions: what the highest value means."
},
"scale_min_label": {
"type": "string",
"default": "",
"maxLength": 60,
"description": "Scale questions: what the lowest value means."
}
}
},
"maxItems": 50,
"minItems": 1,
"description": "1 to 50 questions, in order."
},
"time_zone": {
"type": "string",
"default": "America/Anchorage",
"maxLength": 64,
"minLength": 1,
"description": "The IANA time zone of its dates and run time."
},
"index_name": {
"type": "string",
"default": "",
"maxLength": 80,
"description": "A name for the composite of the poll's Better-Worse index questions, such as \"AI Economy Index\"; empty for \"Composite Better-Worse index\". Shown only when two or more questions have the index."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
{
"type": "null"
}
],
"default": null,
"description": "The first day it runs, YYYY-MM-DD in time_zone; needs run_time."
},
"change_note": {
"type": "string",
"default": "",
"maxLength": 500,
"description": "Why this version differs from the last, kept in the poll's history."
},
"description": {
"type": "string",
"default": "",
"maxLength": 2000,
"description": "What the poll is for, or empty."
},
"run_weekday": {
"anyOf": [
{
"type": "integer",
"maximum": 6,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Weekly polls: the day it runs, 0 = Sunday."
},
"search_depth": {
"type": "integer",
"default": 1,
"maximum": 3,
"minimum": 1,
"description": "Searches allowed per answer, for every model with search on."
},
"restored_from": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "The earlier version this one was started from, or null."
},
"system_prompt": {
"type": "string",
"default": "",
"maxLength": 4000,
"description": "The system prompt every wording is asked under unless it has its own; empty for none."
},
"sample_percent": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "The share of the poll's wordings each scheduled run asks, 1 to 100 percent; every wording is asked once before any is asked again. Left out: unchanged (100 for a new poll). run_poll_now asks this share with share=true, every wording otherwise."
},
"samples_per_cell": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "How many times each model is asked each wording per run, 1 to 50: more samples, narrower ranges."
}
}
}