Text answer

Text-answer tasks present a question and a free-text box. Instead of selecting from predefined options, annotators write their answer in their own words.

Each datapoint can optionally carry a single media subject — one already-uploaded video, image, or audio clip rendered above the question, so annotators describe or react to what they see. For video and audio subjects, the annotator must observe most of the clip before they can submit.

When to use it

• Open-ended feedback ("What did you like or dislike about this product?")
• Descriptions of media ("Describe what happens in this clip")
• Qualitative follow-ups that structured options can't capture
• Verbatims for downstream analysis (samples surface in reports and Ask Your Report)

Datapoint shape

A plain open question sends an empty media object; the question itself lives in the job instruction (or the step instruction inside a chain):

{
  "media": {},
  "context": "The tagline: “Just do it.”"
}

Adding a media subject

To ask about a clip or image, upload it first with POST /media, then reference the returned handle from the datapoint's media.subject — the same two-step flow as a multiple-choice subject:

{
  "context": "Describe what the worker is doing.",
  "media": {
    "subject": [
      { "media_id": "b6a1cd3f-1234-4a2b-9c8d-0e1f2a3b4c5d" }
    ]
  }
}

A subject does not change the submission format or response_options; annotators still submit only their written answer.

Input configuration

All of response_options is optional:

{
  "task_type": "text_answer",
  "response_options": {
    "min_length": 10,
    "max_length": 500,
    "placeholder": "Type your answer…"
  }
}

Result shape

Free text can't be tallied into votes, so the aggregation reports how many people answered plus a bounded sample of the verbatims (up to 50):

{
  "datapoint_index": 0,
  "total_responses": 12,
  "samples": [
    "The pacing feels rushed in the second half.",
    "Loved the colors, but the ending was confusing."
  ],
  "media": [
    {
      "media_id": "b6a1cd3f-1234-4a2b-9c8d-0e1f2a3b4c5d",
      "type": "video",
      "role": "subject",
      "url": "/media/v2/b6a1cd3f-1234-4a2b-9c8d-0e1f2a3b4c5d?sig=..."
    }
  ]
}

Every individual answer is available row-by-row via GET /jobs/{id}/responses, and the report's question block lists the verbatims.

Example

curl -X POST https://api.trydatapoint.com/data-labelling/v1/jobs \
  -H "X-API-Key: $DATAPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "clip-descriptions-v1",
    "instruction": "Watch the clip, then describe what happens.",
    "task_type": "text_answer",
    "response_options": { "min_length": 10, "max_length": 500 },
    "max_responses_per_datapoint": 10,
    "datapoints": [
      {
        "media": {
          "subject": [
            { "media_id": "b6a1cd3f-1234-4a2b-9c8d-0e1f2a3b4c5d" }
          ]
        }
      }
    ]
  }'

Common errors

Next

• Multiple choice: when the answer space is discrete and known in advance
• Chains: follow a structured step with an open-ended "why?"
• API Reference: Jobs: full endpoint reference