Datapoint

Survey Planner

Generate a job plan from a natural-language description.

The Survey Planner takes a plain-English description of what you want to measure and returns a fully-formed POST /jobs payload plus a cost estimate. Use it to prototype surveys, or to power assistants and copilots that create jobs on a user's behalf.

Every plan the endpoint returns is a chain: a top-level steps array of one to five questions (with optional skip_if rules that screen a respondent out after a step — see chains), plus the datapoints to run them against. Submit the returned plan verbatim to POST /jobs.

The endpoint uses AI to draft a plan, then validates it against the same rules as POST /jobs before returning.

Plan a survey

POST/surveys/planAuth: API key

Request body

FieldTypeDescription
description*stringNatural-language description of the survey (10–5000 chars). Include the dp:// or https URLs of any media inline; the planner threads them into the datapoints.
preferencesobjectOptional hints for the planner.
preferences.task_typestringPreferred task type passed to the planner as a hint (e.g. comparison, rating, ranking, multiple_choice). Treated as a suggestion, not a hard constraint; if omitted, the planner picks the best fit.
preferences.max_responsesinteger (1–10000)Advisory hint for the target responses per datapoint (default 10). It is passed to the planner only when it differs from the default, and the planner writes the final max_responses_per_datapoint into the returned plan — the value may not match your hint exactly. To force an exact count, edit max_responses_per_datapoint in the returned plan before submitting it to POST /jobs.

Response (200 OK)

{
  "plan": {
    "name": "logo-preference-v1-a2f8",
    "max_responses_per_datapoint": 10,
    "steps": [
      {
        "task_type": "comparison",
        "instruction": "Which logo looks more professional?"
      }
    ],
    "datapoints": [
      {
        "media": {
          "candidates": [
            { "url": "dp://1fae39d2c7b5/logo_a.svg", "type": "image" },
            { "url": "dp://84b1f6ea3d02/logo_b.svg", "type": "image" }
          ]
        }
      }
    ]
  },
  "summary": "Compares two logo designs on perceived professionalism using 10 annotator responses.",
  "estimated_cost_credits": 50,
  "pricing": {
    "base_credits_per_response": 5,
    "demographic_surcharge_credits": 0,
    "geo_surcharge_credits": 0,
    "credits_per_response": 5
  },
  "warnings": []
}
FieldTypeDescription
planobjectA ready-to-submit POST /jobs payload (runs through the same field-level and handler validation the jobs endpoint uses before being returned). Submit verbatim.
summarystringPlanner-produced 1–3 sentence explanation of what the plan will measure.
estimated_cost_creditsintThe maximum credits this plan can cost. Only fully completed responses bill — walks screened out by a skip_if rule or abandoned mid-chain are never billed, and unused credits are released when the job settles.
pricingobjectPer-response rate breakdown behind the estimate: base_credits_per_response, demographic_surcharge_credits, geo_surcharge_credits, and the effective credits_per_response. See [targeting surcharges](/docs/billing#targeting-surcharges).
warningsarray of stringsNon-blocking notes about the plan — planner caveats such as missing labels or ambiguous instructions, plus any notice that the plan was adjusted before being returned. Read them before submitting, and check the returned `steps` against what you asked for. Empty array if none.

Example

curl -X POST https://api.trydatapoint.com/data-labelling/v1/surveys/plan \
  -H "X-API-Key: $DATAPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Compare logo A (dp://1fae39d2c7b5/logo_a.svg) and logo B (dp://84b1f6ea3d02/logo_b.svg). Which looks more professional?",
    "preferences": { "task_type": "comparison" }
  }'

After reviewing the plan, submit it verbatim:

curl -X POST https://api.trydatapoint.com/data-labelling/v1/jobs \
  -H "X-API-Key: $DATAPOINT_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq .plan plan_response.json)"

Error cases

StatusCause
400The description references dp:// media that doesn't exist or doesn't belong to your account. detail is an object {message, warnings}.
402Insufficient balance to cover the planner fee. detail is an object {message, needed_credits, available_credits}. Top up via POST /billing/checkout and retry.
422Request body failed validation (e.g. description outside 10–5000 chars). detail is an array of field errors.
422The planner produced an invalid plan — for example it referenced dp:// media that doesn't resolve or isn't yours, or a step whose configuration the task-type validator rejects. detail is an object {message, warnings: [...]}.
502The planner failed to produce a plan.
503Planner unavailable.
504Planner timed out. Retry.

Next

  • Jobs: the endpoint you'll submit the plan to
  • Task types: understanding what the planner produced
← PreviousMediaNext →Targeting