submit_query
Submit structured questions to real human workers for judgment calls, evaluations, or tasks unsuited for AI. Returns a query ID for asynchronous response collection.
Instructions
Submit a structured question to real human workers, returning a query_id -- the entry point for any human-in-the-loop (HITL) step: judgment calls, subjective evaluation, approval/review, or "ask a real person" tasks a model should not answer itself. "type" selects the question format (one of: text, multiple_choice, rating_scale, image_comparison, ranking, yes_no, sentiment, image_selection, free_form_text, video_review, audio_review, image_analysis, ab_test, voice_capture, video_capture, photo_capture); "content_data" is the matching type-specific payload (e.g. ab_test: {question, variant_a:{description}, variant_b:{description}}; yes_no: {question}; rating_scale: {question, scale_type, scale_min, scale_max}). Cost/side effects: with a LIVE key this deducts (bid_amount_cents + bonus_amount_cents) * required_responses from balance immediately and dispatches to paid workers (fails if balance too low -- check get_balance or use create_topup_link). With a TEST key, no balance is touched and responses are synthetic, marked simulated: true, so you can build/test a full pipeline for free before going live. Returns immediately, does not wait -- use get_responses (one-shot) or wait_for_responses (bounded polling) to retrieve answers.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Question format/template. One of: text, multiple_choice, rating_scale, image_comparison, ranking, yes_no, sentiment, image_selection, free_form_text, video_review, audio_review, image_analysis, ab_test, voice_capture, video_capture, photo_capture. Determines the required shape of content_data. | |
| title | Yes | Short human-readable title for the query, shown to workers as the task headline (5-255 characters). | |
| description | No | Optional longer explanation/context shown to workers alongside the title, for extra instructions or background. | |
| content_data | Yes | Type-specific payload whose required fields depend on "type" (e.g. {question, variant_a, variant_b} for ab_test; {question} for yes_no; {question, scale_type, scale_min, scale_max} for rating_scale). See the API docs for the full schema per type. | |
| bid_amount_cents | Yes | Cents paid to EACH worker per accepted response (absolute floor 5 = $0.05, max 10000000 = $100,000.00). The REAL minimum is effort-based, not flat: it scales with how long the query type honestly takes a worker to answer, priced at a fair ~$9/hr (0.25 cents/second). Quick types (yes_no, multiple_choice, sentiment, ab_test, headline_test, rating_scale) floor around 5 cents; medium types (image_comparison, image_selection, ranking, text, image_analysis) around 8-12 cents; capture types (voice_capture, photo_capture, custom) around 15 cents; longer types (free_form_text, video_capture) around 30 cents. video_review and audio_review scale with the actual clip length (content_data.video_duration_seconds / audio_duration_seconds) plus a review/write-up overhead, so a 10-minute video review requires roughly $1.65+ -- there is no upper cap, longer clips need proportionally higher bids. Bidding below the type-appropriate minimum is rejected with a 400 telling you the exact floor; call GET /requestor/suggested-bid?type=... for the current min_bid_cents and suggested_bid_cents for a given type before submitting. Total cost = (bid_amount_cents + bonus_amount_cents) * required_responses, deducted from balance in live mode. No charge occurs in test mode. | |
| bonus_amount_cents | No | Optional extra cents paid to EACH worker on top of bid_amount_cents per accepted response (default 0). Included in the total cost calculation. | |
| min_worker_quality | No | Optional minimum worker quality score (0-5) required to accept this query; higher restricts to more experienced/reliable workers. | |
| required_responses | Yes | Number of distinct human worker responses to collect before the query is considered complete (1-1000). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| status | No | ||
| query_id | No | ||
| simulated | No | ||
| total_cost_cents | No | ||
| required_responses | No |