Ask real people: human feedback, user testing, surveys

Opens a call: one short task to several people. With no key, or on the simulated pool, simulated people answer: their answers are made up and marked simulated. Real people answer only on a panel of people who joined it themselves, which any key can make. Returns a call_id at once; ask_people_results gives each person's answers, whether each was typed or pasted, and an evidence level.

Use it only when your user asked for other people's reactions to this material, or said yes when you offered, and the task needs a human reaction a model cannot give: how a song feels, whether a page is clear in ten seconds, whether a game is fun, which version people prefer. Not for your user's own taste (ask them), facts a search can find, or anything done away from a screen.

Who answers: pool defaults to "simulated". Simulated people answer in seconds; every simulated answer carries simulated: true and begins "[simulated] ", and none is a person's view. Real people are rung only on pool "panel:<panel_id>", a panel your user made whose people joined it from its link, in minutes when they are available and never in their quiet hours (9 PM to 8 AM their time by default). Each person is told what is recorded before they take the call.

Cost: during the preview every amount is test money; nothing is charged and nobody receives real pay. max_total_usd (required) is the most your user approved, every fee included. With no approved amount, show your user the for_your_user sentence from ask_people_quote and pass only the amount they approve. A paid call holds the people's pay, a 25% reserve for anyone who takes longer (returned if unused) and a 10% router fee (at least $0.25), each on its own line. A simulated call or a panel at zero pay costs nothing. Nothing opens above max_total_usd (error over_max_total_usd, with the price) or above the key's cap (over_key_cap, with the price and an approve_url for the account owner). If fewer people answer than asked, you pay for those who answered and anyone who stopped partway; anyone still in a seat at the deadline may finish and is paid in full; the rest of the hold returns. A person who stops partway is paid for the time spent, at least 25 cents or the full pay if less; 'Stop: this upset me' pays in full.

content: an https URL (copied into our storage before anyone is asked), {"text": "..."}, or for compare a list of 2 to 6 of these; not used for kind answer. Send only material your user made or may show, and nothing that shows or identifies a person who has not agreed. Ask only for reactions and opinions: calls that ask about health, religion, sexuality, ethnicity, immigration or politics, for a name or any way to reach someone, or for passwords, one-time codes, PINs, keys, government ID, card or bank numbers are refused, and nothing is charged.

Every call is screened before anyone is rung; it may be held for review (state held) or refused (state refused; nothing is charged). Each default used comes back in defaults_used. Look again after next_check_after_seconds. A retry within 24 hours with the same idempotency_key returns the first call; without a key, the same request within 10 minutes counts as the same call, and after that opens a second one.

Example: {"ask":"Listen once to the end. Then say what you felt, in your own words.","kind":"listen","content":"https://example.com/demo-track.mp3","people":3,"answer_fields":{"felt":"text","would_play_again":"boolean"},"max_total_usd":"0.00","idempotency_key":"first-try-1"}

Stops a call. On cancel, nobody new is rung; people already in a seat may finish and are paid in full. Their pay is charged to the hold (test money in the preview: nobody receives real pay), so spent_usd can rise until ask_people_results shows complete: true; the unused hold returns. Returns the call's state and the money so far. Repeating it changes nothing; a cancel cannot be undone.

Use it when your user says the answers in hand are enough or the task has changed. A call closes by itself at its deadline.

Example: {"call_id": "call_..."}

Makes a panel, a named group of people the account owner invites, and returns its panel_id and a join link for your user to share. Each person joins on their own phone, states that they are an adult, is told what is recorded while they answer (how much played, whether the page stayed in front, pauses and replays, typed or pasted), chooses when they can be rung, and can leave at any time. Calls with pool "panel:<panel_id>" then reach only them, and cost nothing at zero pay. On a panel of fewer than five, both sides are told that answers cannot be anonymous.

Use it only when your user asks to set up a group of people they will invite themselves; nobody is added without joining. Any key can make a panel, a free test key too (with no key, the error says how to get one); calls with its pool ring the people who joined, when they are available. A retry with the same idempotency_key returns the same panel; without one, a retry makes a second panel.

Example: {"name": "album-listeners", "idempotency_key": "panel-1"}

Prices a call without opening it: nobody is rung and nothing is spent. Takes the same fields as ask_people, without max_total_usd or idempotency_key. Nothing else is needed first: leave content out until your user gives you the material (the quote is priced from minutes), and leave pay out unless your user named one (left out, it is 0.00 on the simulated pool and on a panel; any pay you set must meet the $18-an-hour floor). Returns each line of the price (the people's pay, each fee, any reserve returned if unused), total_usd, expected_minutes_to_enough, test_money, and for_your_user: a plain sentence to show your user before anything is spent. A quote reads ask and content only for screening and the minutes estimate; it neither fetches a content URL nor keeps the ask or the content.

Use it to get an amount your user can approve, or to see how people, pay or deadline move the price. Not needed when max_total_usd already covers what your user approved: ask_people opens nothing above it.

Example: {"ask":"Which headline makes you want to read on, and why?","kind":"compare","content":[{"text":"Plan a week of dinners in five minutes"},{"text":"Dinner, decided: a week of meals in five minutes"}],"people":12,"pay_per_person_usd":"1.00","minutes":2,"pool":"simulated"}

Returns a call's answers so far, given the call_id from ask_people: first a summary (the state, a tally of each answer field, how many responses reached each evidence level), then one entry per person with their answers and whether each was typed or pasted, then the money (held_usd, spent_usd, returned_usd, and test_money, true throughout the preview: nobody receives real pay). detail: "full" adds each person's record: how much of the material played, whether the page stayed in front, where they paused or replayed.

States: held (under review; nobody rung yet), open, enough (enough answers; more may come until the deadline), then complete, expired, cancelled or refused. Evidence: attended (the material played in real time with its page in front for nearly all its length; that does not show the person watched or listened) or said (an answer without that record; its pay still counts). No level shows that an answer was formed without help.

wait_seconds (up to 25) waits for a new answer; pass the last result's cursor as after to get only new ones; complete: true means the call has closed. Look again after next_check_after_seconds; sooner usually returns nothing new. Simulated answers carry simulated: true and begin "[simulated] ".

Example: {"call_id": "call_...", "after": "", "wait_seconds": 25}

Sends the people who answered a call one line (at most 280 characters, and up to three lines a call) saying what you did with their answers, for example "Cut the intro from 40 to 12 seconds; most of you drifted there." The line is reviewed the way a call is and may be refused; if allowed, it appears on each answering person's receipt and they are notified. Costs nothing. Returns whether the line was allowed and how many people it reached. With an idempotency_key, a repeat with the same key changes nothing; without one, the same line sent again within 10 minutes counts as the same send.

Use it, with your user's agreement, once the answers have changed the work. Not for questions or new tasks (open a new call), and never for anything that identifies a person.

Example: {"call_id": "call_...", "text": "Cut the intro from 40 to 12 seconds; most of you drifted there.", "idempotency_key": "outcome-1"}