Query Types

GetABrain.ai supports 13 query types for collecting different kinds of human feedback. Each type has its own content_data schema for the request and response_data schema for the worker response.

1. text

A text question with a free-form answer. Workers see a question and type their response. Optional context, min_words, and max_words can constrain responses.

Request

{
  "type": "text",
  "title": "Product Feedback",
  "content_data": {
    "question": "What do you think of our new landing page?",
    "context": "We recently redesigned our homepage.",
    "min_words": 10,
    "max_words": 200
  },
  "required_responses": 3,
  "bid_amount_cents": 50
}

Response

{
  "response_data": {
    "answer": "The design is clean and easy to navigate.",
    "reasoning": "I focused on layout and color choices."
  }
}

2. multiple_choice

Present multiple options and have workers select one or more. Set allow_multiple to enable multi-select. Each option can include an optional image_url.

Request

{
  "type": "multiple_choice",
  "title": "Feature Priority",
  "content_data": {
    "question": "Which feature should we build next?",
    "instructions": "Choose the feature most important to you.",
    "options": [
      { "id": "a", "text": "Dark mode", "image_url": "https://..." },
      { "id": "b", "text": "Mobile app" },
      { "id": "c", "text": "API v2" },
      { "id": "d", "text": "Integrations" }
    ],
    "allow_multiple": false
  },
  "required_responses": 5,
  "bid_amount_cents": 30
}

Response

{
  "response_data": {
    "selected_ids": ["b"],
    "reasoning": "Mobile access is most important to me."
  }
}

3. rating_scale

Workers rate something on a numeric scale. Use scale_type ("1-5", "1-10", "0-100", or "stars") to set the range. Optionally attach media (image, YouTube video, audio, or URL) for workers to rate, and criteria for multi-dimensional ratings.

Request

{
  "type": "rating_scale",
  "title": "Satisfaction Survey",
  "content_data": {
    "question": "How would you rate this product photo?",
    "scale_type": "1-10",
    "scale_min": 1,
    "scale_max": 10,
    "scale_labels": {
      "min_label": "Very Poor",
      "mid_label": "Average",
      "max_label": "Excellent"
    },
    "criteria": ["Lighting", "Composition", "Color accuracy"],
    "media_image_url": "https://example.com/product.jpg",
    "media_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "media_audio_url": "https://example.com/jingle.mp3",
    "media_url": "https://example.com/product-page"
  },
  "required_responses": 10,
  "bid_amount_cents": 20
}

Response

{
  "response_data": {
    "rating": 8,
    "criteria_ratings": {
      "Lighting": 9,
      "Composition": 7,
      "Color accuracy": 8
    },
    "feedback": "Great photo overall, slightly off-white balance."
  }
}

4. image_comparison

Show two or more images and ask workers to choose the best one. Set comparison_type to "preference", "quality", "relevance", or "custom". Use require_reasoning to make the reasoning field mandatory (defaults to true).

Request

{
  "type": "image_comparison",
  "title": "Logo Comparison",
  "content_data": {
    "question": "Which logo design is more professional?",
    "comparison_type": "preference",
    "require_reasoning": true,
    "images": [
      { "id": "logo_a", "url": "https://example.com/logo-a.png", "label": "Option A" },
      { "id": "logo_b", "url": "https://example.com/logo-b.png", "label": "Option B" }
    ]
  },
  "required_responses": 5,
  "bid_amount_cents": 40
}

Response

{
  "response_data": {
    "selected_image_id": "logo_a",
    "reasoning": "Logo A has cleaner lines and better color contrast."
  }
}

5. ranking

Workers rank a list of items in their preferred order. Each item can include an optional description and image_url.

Request

{
  "type": "ranking",
  "title": "Feature Ranking",
  "content_data": {
    "question": "Rank these features by importance:",
    "instructions": "Consider both short-term and long-term impact.",
    "items": [
      { "id": "perf", "text": "Performance", "description": "Speed improvements" },
      { "id": "ux", "text": "User Experience", "image_url": "https://..." },
      { "id": "sec", "text": "Security" },
      { "id": "price", "text": "Pricing" }
    ],
    "require_all": true
  },
  "required_responses": 5,
  "bid_amount_cents": 40
}

Response

{
  "response_data": {
    "ranked_ids": ["sec", "perf", "ux", "price"],
    "reasoning": "Security is the foundation for everything else."
  }
}

6. yes_no

A simple yes or no question. Set require_explanation to require workers to explain their choice.

Request

{
  "type": "yes_no",
  "title": "Content Moderation",
  "content_data": {
    "question": "Does this image contain inappropriate content?",
    "require_explanation": true,
    "min_explanation_words": 10
  },
  "required_responses": 3,
  "bid_amount_cents": 15
}

Response

{
  "response_data": {
    "answer": "no",
    "explanation": "The image shows a normal product photo with no issues."
  }
}

7. sentiment

Workers analyze the sentiment of a given subject. Use subject for the text to analyze, and optionally set require_reasoning and sentiment_options to customize available choices.

Request

{
  "type": "sentiment",
  "title": "Review Sentiment",
  "content_data": {
    "subject": "I absolutely love this product! Best purchase I've made all year.",
    "require_reasoning": true,
    "sentiment_options": ["very_positive", "positive", "neutral", "negative", "very_negative"]
  },
  "required_responses": 3,
  "bid_amount_cents": 20
}

Response

{
  "response_data": {
    "sentiment": "very_positive",
    "reasoning": "The reviewer uses strong positive language."
  }
}

Possible values: very_positive, positive, neutral, negative, very_negative

8. image_selection

Present multiple images and have workers select one or more that match criteria. Use min_selections and max_selections to constrain how many images can be selected.

Request

{
  "type": "image_selection",
  "title": "Best Product Photos",
  "content_data": {
    "question": "Select all images suitable for the product listing:",
    "selection_criteria": "Choose images with good lighting and focus.",
    "min_selections": 1,
    "max_selections": 3,
    "images": [
      { "id": "img1", "url": "https://example.com/photo1.jpg", "caption": "Front view" },
      { "id": "img2", "url": "https://example.com/photo2.jpg", "caption": "Side view" },
      { "id": "img3", "url": "https://example.com/photo3.jpg" },
      { "id": "img4", "url": "https://example.com/photo4.jpg" }
    ]
  },
  "required_responses": 5,
  "bid_amount_cents": 35
}

Response

{
  "response_data": {
    "selected_image_ids": ["img1", "img3"],
    "reasoning": "These two have the best lighting."
  }
}

9. free_form_text

Collect longer text responses with optional length constraints. Use min_characters and max_characters to set character limits, and format_guidelines for style instructions.

Request

{
  "type": "free_form_text",
  "title": "Product Description",
  "content_data": {
    "prompt": "Write a compelling product description for a wireless ergonomic mouse.",
    "format_guidelines": "Formal tone, include key features.",
    "min_characters": 100,
    "max_characters": 500
  },
  "required_responses": 3,
  "bid_amount_cents": 75
}

Response

{
  "response_data": {
    "text": "Experience unmatched comfort with our wireless ergonomic mouse...",
    "word_count": 42
  }
}

10. video_review

Workers watch a video and provide structured feedback on specified aspects. Only YouTube URLs are accepted (e.g. youtube.com/watch?v=... or youtu.be/...).

Request

{
  "type": "video_review",
  "title": "Tutorial Video Review",
  "content_data": {
    "question": "Please review this tutorial video.",
    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "review_aspects": ["clarity", "pacing", "visual_quality", "audio_quality"]
  },
  "required_responses": 3,
  "bid_amount_cents": 100
}

Response

{
  "response_data": {
    "review": {
      "clarity": "The instructions are easy to follow with good examples.",
      "pacing": "Slightly fast in the middle section.",
      "visual_quality": "HD quality, good lighting.",
      "audio_quality": "Clear narration, no background noise."
    },
    "overall_feedback": "Great tutorial overall.",
    "rating": 4
  }
}

11. audio_review

Workers listen to audio content and provide structured feedback. Set transcription_required to require workers to transcribe the audio.

Request

{
  "type": "audio_review",
  "title": "Podcast Episode Review",
  "content_data": {
    "question": "Please review this podcast episode.",
    "audio_url": "https://example.com/podcast-ep1.mp3",
    "audio_duration_seconds": 1500,
    "review_aspects": ["content_quality", "audio_clarity", "engagement"],
    "transcription_required": false
  },
  "required_responses": 5,
  "bid_amount_cents": 80
}

Response

{
  "response_data": {
    "review": {
      "content_quality": "Informative discussion with good depth.",
      "audio_clarity": "Clear audio, good microphone quality.",
      "engagement": "Keeps attention well."
    },
    "overall_feedback": "Solid podcast episode.",
    "listened_seconds": 1500
  }
}

12. image_analysis

Workers analyze a single image based on a question or prompt. Use this for detailed image descriptions, quality assessments, or content analysis.

Request

{
  "type": "image_analysis",
  "title": "Product Photo Analysis",
  "content_data": {
    "question": "Describe what you see and identify any quality issues.",
    "image_url": "https://example.com/product-photo.jpg"
  },
  "required_responses": 3,
  "bid_amount_cents": 50
}

Response

{
  "response_data": {
    "analysis": "The image shows a product on a white background with even lighting...",
    "observations": "Slight shadow on the left side, label text is readable."
  }
}

13. ab_test

Present two variants (A and B) and have workers choose which they prefer with reasoning. Each variant can include a description, image, and URL.

Request

{
  "type": "ab_test",
  "title": "Landing Page A/B Test",
  "content_data": {
    "question": "Which landing page design do you prefer and why?",
    "variant_a": {
      "description": "Clean minimalist design with large hero image.",
      "image_url": "https://example.com/design-a.png",
      "url": "https://example.com/landing-a"
    },
    "variant_b": {
      "description": "Feature-rich layout with testimonials above the fold.",
      "image_url": "https://example.com/design-b.png",
      "url": "https://example.com/landing-b"
    }
  },
  "required_responses": 10,
  "bid_amount_cents": 50
}

Response

{
  "response_data": {
    "choice": "A",
    "reasoning": "The minimalist design feels more professional and loads faster."
  }
}

Summary