API

Every chart is one HTTP call away

JSON in, JSON out. Authenticate with a bearer API key from the billing page, or with a session cookie if you are calling from a browser already signed in.

POST /v1/query

Get a chart

Runs the whole pipeline and returns the finished figure, the chart config, the row count and every warning it raised on the way. It returns a figure even when a stage had to fall back.

curl -X POST https://twohelixes.com/v1/query \
  -H "Authorization: Bearer $TWOHELIXES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"revenue by region this quarter","source_id":"..."}'

POST /v1/query/stream

Stream the run

The same call as server-sent events, so a long run can show its progress and its partial chart as it goes. Event names: stage, thought, warning, partial, result, done.

curl -N -X POST https://twohelixes.com/v1/query/stream \
  -H "Authorization: Bearer $TWOHELIXES_KEY" \
  -d '{"q":"which regions are shrinking?"}'

POST /v1/sql/generate

Generate SQL

Schema-aware SQL for a question. The statement is checked read-only before it is returned, and again before any driver executes it.

curl -X POST https://twohelixes.com/v1/sql/generate \
  -H "Authorization: Bearer $TWOHELIXES_KEY" \
  -d '{"source_id":"...","question":"top customers by lifetime value"}'

GET /v1/chart/{id}/export

Export a chart

SVG, PNG or CSV. SVG is drawn by our own exporter - deterministic, no headless browser, and editable markup.

curl "https://twohelixes.com/v1/chart/$ID/export?format=svg&mode=dark" \
  -H "Authorization: Bearer $TWOHELIXES_KEY"

POST /v1/agent

Run a deep-research agent

Starts a long-running agent and returns a job id immediately - no SSE connection to hold open. Billed as a base fee plus credits per minute while it runs; a run that produces nothing is refunded in full. Poll /v1/jobs/{id} for progress, findings and an itemised bill.

curl -X POST https://twohelixes.com/v1/agent \
  -H "Authorization: Bearer $TWOHELIXES_KEY" \
  -d '{"goal":"why did south shrink last quarter?","source_id":"..."}'

GET /v1/usage

See what is running and what it costs

Every meter: what is open right now, the rate it is burning, the minutes already billed and how many minutes your balance covers. The per-minute charges in the ledger can all be traced back to a row here.

curl https://twohelixes.com/v1/usage \
  -H "Authorization: Bearer $TWOHELIXES_KEY"

GET /v1/chart/{id}/notebook

Export a notebook

The whole run as a notebook: the data, the transformation that was run and the chart rebuilt with the same palette. format=ipynb for Jupyter, or the default marimo file, which we can also host for you.

curl -O -J "https://twohelixes.com/v1/chart/$ID/notebook?format=ipynb" \
  -H "Authorization: Bearer $TWOHELIXES_KEY"

Analytics compatibility

The GA4 parity map states exactly what matches, what is partial, and what twoHelixes deliberately does differently.

Read the parity map

Rate limits

Anonymous callers get 1 sample-data question a day, per address. Free accounts get 10 AI charts a month under per-minute and per-day limits. Requests paid for from credits are not rate limited beyond a global per-account safety valve, and the unit price falls automatically with your trailing 30-day spend.

Charging happens after success — a failed pipeline does not spend anything.
Generated SQL is checked read-only before it reaches a driver, on every path.
Every response carries the warnings the run produced, so a degraded answer is never silently a clean one.

Get an API key