Run human-evaluation surveys from your terminal: A/B preference tests, ratings, rankings, and classification — on text, images, audio, and video. Get real human opinions, then read aggregated results back in your shell.
datapoint is a command-line client for Datapoint AI.
It wraps the same public API used by the editor integrations, so you can design a
survey, launch it to a panel of real humans, and pick up results a few minutes
later — without leaving the terminal.
pip install datapoint-ai
# or, run without installing:
uvx --from datapoint-ai datapoint --help
# or, isolated install:
pipx install datapoint-aiThe PyPI package is datapoint-ai; the installed command is datapoint.
Requires Python 3.10+.
datapoint login # opens your browser to sign in
datapoint balance
datapoint media upload ./logo-a.png ./logo-b.png
datapoint survey plan "Compare logo A (dp://media/abc.png) and \
logo B (dp://media/def.png). Target: software engineers." \
--max-responses 20 --save plan.json
datapoint survey create plan.json # shows cost, asks to confirm
datapoint survey status JOB_ID
datapoint survey responses JOB_IDdatapoint login | logout | whoami
datapoint balance
datapoint subscription
datapoint credits buy [PRODUCT_ID] [--open]
datapoint billing portal [--open]
datapoint media upload FILES...
datapoint survey plan DESCRIPTION [--max-responses N] [--save FILE]
datapoint survey create PLAN_FILE [--yes]
datapoint survey list
datapoint survey status JOB_ID [--results]
datapoint survey responses JOB_ID [--page N] [--per-page N]
[--include-abandoned] [--include-in-progress]
datapoint survey pause | resume | retry JOB_ID
datapoint survey cancel JOB_ID [--yes]
datapoint survey report JOB_ID
datapoint filters [--country C] [--region R] [--city K] [--postal P]
[--field F] [--offset N] [--limit N]
Every read command supports --json for machine-readable output you can pipe
into jq or another tool.
survey create reserves credits and dispatches paid human work within seconds —
there is no draft or staging state. So it prints the plan summary and cost and
asks you to confirm before launching:
$ datapoint survey create plan.json
Survey: Logo memorability A vs B
Task type: comparison
Datapoints: 1
Responses per datapoint: 20
Estimated cost: 100 credits
This reserves 100 credits and dispatches paid human work. Continue? [y/N]:
Pass --yes to skip the prompt in scripts (after a human has reviewed the plan).
| Variable | Description |
|---|---|
DATAPOINT_API_KEY |
API key (overrides saved config). |
DATAPOINT_BASE_URL |
API base URL (default https://api.trydatapoint.com/data-labelling/v1). |
Your API key is saved to ~/.config/datapoint/config.json (%APPDATA%\datapoint\config.json
on Windows) with owner-only permissions. The Datapoint editor integration reads
the same file, so logging in once authenticates both.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Generic error |
| 2 | Not authenticated |
| 3 | Insufficient credits |
| 4 | Rate limited |
Set DATAPOINT_DEBUG=1 to print full tracebacks on unexpected errors.
MIT — see LICENSE.