Chains

A chain bundles 1 to 5 task-type steps into a single survey. Each annotator answers the steps in order, and you get aggregated results per step. Use chains when later questions depend on earlier ones: gate a quality rating behind a watchability check, follow a tag selection with a confidence rating, or run a comparison and ask annotators to back up their choice.

When to use it

• Quality gate before scoring. Ask "is this clip watchable?" first; rate realism only when the answer is yes.
• Tag, then rate. Pick which categories apply, then score how strongly each one is present.
• Comparison + follow-up. Choose A or B, then answer a rating about the winner.
• Branching surveys. End the chain early on a specific answer to skip irrelevant downstream steps.

If your survey is a single question, use one of the standalone task types instead. Chains add ordering and skip_if plumbing you don't need for a single-step job.

Job shape

A chain job replaces the standalone fields (instruction, task_type, response_options) with a top-level steps array:

{
  "name": "video-quality-chain-v1",
  "max_responses_per_datapoint": 10,
  "steps": [
    {
      "task_type": "multiple_choice",
      "instruction": "Is this clip watchable?",
      "response_options": { "mode": "single" },
      "skip_if": { "when_answer_equals": "no" }
    },
    {
      "task_type": "rating",
      "instruction": "Rate how realistic this clip looks.",
      "response_options": { "scale": [1, 2, 3, 4, 5] }
    }
  ],
  "datapoints": [
    {
      "media_per_step": {
        "0": {
          "options": [
            { "id": "yes", "text": "Yes" },
            { "id": "no",  "text": "No" }
          ]
        },
        "1": {
          "subject": [
            { "url": "dp://e7d921ab3c45/sample.mp4", "type": "video" }
          ]
        }
      }
    }
  ]
}

Step shape

Skip rules

skip_if lives on a step and inspects the annotator's submission to that step. When the rule matches, every later step is skipped for that annotator. Three forms are accepted:

when_answer_equals

The simplest form: match an exact value. Use it for binary or single-pick gates.

{
  "task_type": "multiple_choice",
  "instruction": "Is this clip watchable?",
  "response_options": { "mode": "single" },
  "skip_if": { "when_answer_equals": "no" }
}

For a rating step, the value is the numeric rating:

{
  "task_type": "rating",
  "instruction": "How clear was the audio?",
  "response_options": { "scale": [1, 2, 3, 4, 5] },
  "skip_if": { "when_answer_equals": 1 }
}

when_answer_in

Match against a list of acceptable answers. Useful when several values mean "stop here":

{
  "task_type": "multiple_choice",
  "instruction": "Did you understand the speaker?",
  "response_options": { "mode": "single" },
  "skip_if": { "when_answer_in": ["no", "unsure"] }
}

For multi-select multiple-choice, the rule fires if any picked option appears in the list:

{
  "response_options": { "mode": "multi" },
  "skip_if": { "when_answer_in": ["spam", "broken"] }
}

predicate (escape hatch)

For comparisons the shorthand doesn't cover (numeric ranges, negation, compound logic), supply a JSON-Logic predicate directly. Supported operators: ==, !=, <, <=, >, >=, in, and, or, !, var. Predicates are nested up to 6 levels deep.

{
  "task_type": "rating",
  "instruction": "How realistic is this clip?",
  "response_options": { "scale": [1, 2, 3, 4, 5] },
  "skip_if": {
    "predicate": {
      "<": [{ "var": "rating" }, 3]
    }
  }
}

Reads as: "skip the rest of the chain if the rating is below 3."

The submission field name (rating, choice, choices, ranking) is set by the step's task type. Predicates referencing unknown field paths are rejected at job-creation time.

Per-step media

By default, every step in a chain operates on the same media object you put on the datapoint. When steps need different shapes (for example, a multiple-choice option list followed by a rating subject), use media_per_step instead, keyed by string step index. The Job shape example above uses this form.

Keys must be the digit strings "0", "1", ... and must cover every step in the parent steps array (no missing or extra keys). media and media_per_step are mutually exclusive: set exactly one per datapoint.

How responses are counted

Only a qualified walk — one that completes every step — counts toward max_responses_per_datapoint and is billed. A walk that ends early through a skip_if rule finalizes as screened out: it is free (never billed), and it does not advance your target. Walks the annotator abandons partway through are likewise never billed and never counted.

Because some walks screen out or are abandoned, the platform keeps serving a datapoint until it has collected enough qualified walks (or it reaches a platform serving limit for that datapoint, or exhausts the eligible audience). You're billed only for qualified walks, up to max_responses_per_datapoint per datapoint.

GET /jobs/{id} returns a per-job chain_progress rollup so you can watch this fill:

{
  "chain_progress": {
    "target_responses": 200,
    "completed_responses": 143,
    "screened_out_responses": 27
  }
}

Result shape

GET /jobs/{id}/results returns one entry per original datapoint, with a steps array carrying the per-step aggregation. Each step entry uses the same fields you'd see for a standalone job of that task type:

{
  "datapoint_index": 0,
  "context": null,
  "steps": [
    {
      "step_index": 0,
      "task_type": "multiple_choice",
      "votes": { "yes": 10 },
      "total_responses": 10,
      "consensus": "yes",
      "confidence": 1.0
    },
    {
      "step_index": 1,
      "task_type": "rating",
      "mean": 3.9,
      "median": 4,
      "distribution": { "3": 3, "4": 5, "5": 2 },
      "total_responses": 10
    }
  ]
}

step_index is zero-based and matches the position in your request's steps array. Results count only qualified walks, so every step reports the same total_responses — the number of walks that finished the entire chain. A gate step therefore surfaces only the answers that let a walk continue (here, all 10 qualified walks answered "yes"); the screened-out answers and the full step-by-step funnel are visible in the served view of GET /jobs/{id}/responses, not in results. Each step entry also carries the reliability-weighted verdict fields (weighted_votes, weighted_consensus, and their per-type analogues) beside their equal-vote counterparts, exactly as a standalone job of that task type does — see Task types.

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": "video-quality-chain-v1",
    "max_responses_per_datapoint": 10,
    "steps": [
      {
        "task_type": "multiple_choice",
        "instruction": "Is this clip watchable?",
        "response_options": { "mode": "single" },
        "skip_if": { "when_answer_equals": "no" }
      },
      {
        "task_type": "rating",
        "instruction": "Rate how realistic this clip looks.",
        "response_options": { "scale": [1, 2, 3, 4, 5] }
      }
    ],
    "datapoints": [
      {
        "media_per_step": {
          "0": {
            "options": [
              { "id": "yes", "text": "Yes" },
              { "id": "no",  "text": "No" }
            ]
          },
          "1": {
            "subject": [
              { "url": "dp://e7d921ab3c45/sample.mp4", "type": "video" }
            ]
          }
        }
      }
    ]
  }'

Common errors

Retrying

Chain jobs support POST /jobs/{id}/retry. Retrying a failed step re-queues the entire chain instance — all of its sibling steps — so the walk runs again from the start. The one exception: an instance can't be retried if one of its steps was blocked by content review.

Next

• Survey Planner: describe a chain in plain English and let the planner build it
• Task types: the building blocks each step is built from
• API Reference: Jobs: full request and response shapes