To add human feedback to a workflow, call four steps in order: estimate the price and time, ask one question with an idempotency key, wait for the result, then act on it. The estimate is free. The key makes a retry safe. Waiting happens on our side, so you don't poll.

This post uses the 50heads API. The developer docs and API reference are the source of truth for every field.

When a human check is worth making

A person's choice is the right input when:

  • the decision is a preference, such as which headline, name or image;
  • a wrong choice costs more than the question;
  • an automated check can't settle it.

It is the wrong input for facts you can look up, or when you need the answer in under a second. A typical result takes about ten minutes. That is typical, not guaranteed.

The four steps

  1. Estimate. Price, time and validation. It never spends.
  2. Ask. Post the question with an idempotency key.
  3. Wait. The API holds your request until answers arrive.
  4. Act. Read the leader, the margin and how strong the lead is.

Example

Set a key, then run the three calls. Keys are for servers. Requests from a browser are refused, so never put a key in a web page.

# 1. Estimate: free, no key needed
curl https://api.50heads.com/v1/billing/estimate \
  -H "Content-Type: application/json" \
  -d '{"draft":{"type":"single_choice","text":"Which menu would you order from tonight?",
       "options":[{"label":"Menu A"},{"label":"Menu B"}],"n":50,"tier":1}}'

# 2. Ask: one UUID per question
curl https://api.50heads.com/v2/questions \
  -H "Authorization: Bearer $FIFTYHEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"draft":{"type":"single_choice","text":"Which menu would you order from tonight?",
       "options":[{"label":"Menu A"},{"label":"Menu B"}],"n":50,"tier":1,"language":"en"}}'

# 3. Wait: up to 25 seconds a call, repeat while "done" is false
curl "https://api.50heads.com/v2/questions/q_8k2f/wait?seconds=25" \
  -H "Authorization: Bearer $FIFTYHEADS_API_KEY"

A fifty-answer Tier 1 question costs $13. The quick start has the same flow in TypeScript and Python.

Idempotency keys

POST /v2/questions needs an Idempotency-Key header, a UUID you make for each question.

  • If a request times out, send it again with the same key. You get the original question back, never a second ask.
  • Keys are kept for 24 hours.
  • The same key with a different body returns idempotency_conflict.

Make the key before the first attempt and store it with your record of the decision. If you create a new key on each retry, you defeat the point.

Waiting for the result

Don't poll in a tight loop. GET /v2/questions/{id}/wait?seconds=25 holds the request until the question is answered or 25 seconds pass. Call it again while done is false.

Or register a webhook and we will call your URL. Check the signature before you trust the payload, and use the event id to ignore repeats, as deliveries can arrive twice or out of order.

Set your own overall deadline. If the answer doesn't arrive in time, decide what your product does anyway.

Failure paths

Branch on the error code, never on the message.

Code What it means What to do
insufficient_credits Balance is too low Top up, or skip the check
spend_cap_exceeded The key's daily cap would be passed Wait for the reset, or raise the cap deliberately
content_refused The question breaks the acceptable use policy Change the question. Nothing is spent
idempotency_conflict Same key, different body Make a new key for a changed question
rate_limited Over 60 requests a minute or 10 asks a minute Wait for Retry-After seconds
unavailable Asking is paused for maintenance Retry later

Also plan for an underfilled question. If fewer heads answer than you asked for, you pay only for the answers you get, and the result shows how many answered. Check the count before you act.

Keep spend bounded

Every key has scopes and a daily spend cap, set when you make it. See API keys and spend caps. Give each key only the scopes it needs. Use list_questions in the MCP server, or the question list in the API, to reuse a recent answer before asking again.

Acting on the result

The result gives the leader, the margin in percentage points and how strong the lead is for the number of answers. Decide your rule in advance:

  • Strong lead: proceed with the leader.
  • Weak lead: treat the options as close, and choose on another basis or ask more.

The result shows what this group chose. It is not proof that the winner is best.

Next step

Make a key and run the estimate. Open the docs for the quick start, or see pricing. The estimate charges nothing.