API reference

POST/v1/billing/estimate

Price, time and validation for a question draft.

No authentication.

Counts as half a request against the rate limit. validation lists anything that would stop the ask, one issue per field.

GET/v1/config

Credit exchange rates, the country table and question languages.

No authentication.

GET/v1/templates

Fixed-price question templates.

No authentication.

GET/v1/public/countries

Where heads answer from, the languages they read and pool size bands by tier.

No authentication.

GET/v1/tags

The self-declared tags you can target at any tier, by group (one trait per group).

No authentication.

GET/v1/public/stats

Heads online now, answers this week and the median time to fifty answers.

No authentication.

POST/v2/questions

Ask a question.

API key or OAuth token with questions:write. Idempotency-Key header required.

Requires an Idempotency-Key header (a UUID). The same key returns the same question for 24 hours; a different body with the same key is idempotency_conflict. Fails with insufficient_credits, spend_cap_exceeded or content_refused without spending anything.

GET/v2/questions

Your questions, newest first.

API key or OAuth token with questions:read.

GET/v2/questions/{id}

One question and its progress.

API key or OAuth token with questions:read.

PATCH/v2/questions/{id}

Complete early once minAnswers heads have answered, or file it: project, labels, archive, bookmark and a set-once externalRef.

API key or OAuth token with questions:write.

If that many have already answered, the question closes now and what was not answered is refunded. Changing an externalRef once set is refused with 409 external_ref_set.

GET/v2/questions/labels

Labels in use in the account, most used first.

API key or OAuth token with questions:read.

GET/v2/questions/{id}/result

The result so far. Partial while the question is live.

API key or OAuth token with questions:read.

With a filter, the distribution, breakdowns and answers are of matching answers only; nUnfiltered counts them all and suppressed is true when a country or age band matched too few to show. insights is the summary of written answers once there is one.

GET/v2/questions/{id}/answers

Matching answers, newest first, a page at a time, with reasons and translations.

API key or OAuth token with questions:read.

GET/v2/questions/{id}/insights

The summary of the written answers: themes with counts and quotes, sentiment, a takeaway.

API key or OAuth token with questions:read.

Made by a machine from the reasons and free text, never from who answered; counts and quotes are computed from the answers. Written in the account's language, with the question-language original.

POST/v2/questions/{id}/insights

Make a fresh summary now: once every 10 minutes while live; the final one when it closes.

API key or OAuth token with questions:read.

429 rate_limited with retryAfterMs while a recent summary stands; 409 too_few_answers under three written answers.

GET/v2/questions/{id}/wait

Hold the request until the question is answered, up to 25 seconds a call.

API key or OAuth token with questions:read.

Call again while done is false. minAnswers completes early once that many heads have answered.

POST/v2/questions/{id}/cancel

Stop a live question and refund the answers not given.

API key or OAuth token with questions:write.

POST/v2/questions/{id}/share

Turn the public results page on or off.

API key or OAuth token with questions:write.

GET/v2/questions/{id}/export.csv

Every answer as CSV: option or text, reason, translations, tier, attestation reference, time, and taps for a click test.

API key or OAuth token with questions:read.

GET/v2/questions/{id}/export.pdf

A one-page PDF report: the question, the chart, what it means and the answers (pinned first).

API key or OAuth token with questions:read.

GET/v2/questions/{id}/export.png

The chart as a PNG to share: size=square (1080×1080, default), wide (1200×675) or story (1080×1920).

API key or OAuth token with questions:read.

POST/v2/questions/{id}/exports

A PDF report or PNG chart as a signed link that works for an hour without signing in.

API key or OAuth token with questions:read.

POST/v2/questions/{id}/heads

Reopen a finished question for n more heads, same wording and targeting; answers merge. dryRun quotes only.

API key or OAuth token with questions:write. Idempotency-Key header required.

Needs an Idempotency-Key unless dryRun. The question must be complete or underfilled.

POST/v2/questions/{id}/answers/{ref}/flag

Flag one answer, named by its attestation reference, for review. Upheld: removed and refunded.

API key or OAuth token with questions:write.

POST/v2/questions/{id}/answers/{ref}/pin

Pin an answer to the top of the results and the PDF report, or unpin it.

API key or OAuth token with questions:write.

GET/v2/questions/{id}/share-links

Private share links for a question (tokens are never shown again).

API key or OAuth token with questions:read.

POST/v2/questions/{id}/share-links

A private, unlisted link to the full results with written answers; expires in 1 to 90 days.

API key or OAuth token with questions:write.

DELETE/v2/questions/{id}/share-links/{linkId}

Revoke a private share link; it stops working at once.

API key or OAuth token with questions:write.

GET/v1/public/shared/{token}

The results behind a private share link. No sign-in; never cached; noindex.

No authentication.

GET/v2/questions/{id}/heatmap.png

A click test's heatmap as a transparent PNG to lay over the image. Add ?aspect=width/height to match it.

API key or OAuth token with questions:read.

POST/v2/questions/{id}/dispute

Dispute a result within 7 days of it closing.

API key or OAuth token with questions:write.

GET/v1/public/results/{code}

A result its requester made public.

No authentication.

GET/v1/drafts

Saved drafts.

API key or OAuth token with questions:read.