View as Markdown

REST API

The Python library is a thin layer over this API; anything it does, you can do over HTTP.

Basics

Base URL https://app.predictabl.tech/pub/v1
Authentication Authorization: Bearer pk_... (get a token)
Format JSON in and out; uploads are multipart/form-data

Every response has the same envelope:

{"data": { ... }, "error": null}
{"data": null, "error": {"code": "NOT_FOUND", "message": "Run not found", "details": null}}

Key and access problems answer 401 or 403 with {"detail": "..."} instead. All error codes.

The examples below use:

export P=https://app.predictabl.tech/pub/v1
export AUTH="Authorization: Bearer $PREDICTABL_API_KEY"

Score with a trained model

Any token can do these, including a Predictions only one.

List your models

curl -s "$P/runs?limit=50" -H "$AUTH"

Each item has id, state (SUCCEEDED when ready), opportunity_title (what it predicts) and headline_metric. GET /runs/{id} adds kind and meaning, and GET /runs/{id}/results the full test results.

Score records

curl -s -X POST "$P/runs/$MODEL_ID/predict-records" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"rows": [{"tenure": 2, "Contract": "Month-to-month", "MonthlyCharges": 89.1}]}'
{"data": {"run_id": "...", "task": "binary_classification", "target": "churned",
          "meaning": "probability that customer churned",
          "count": 1, "predictions": [{"entity_id": "0", "prediction": 0.71}]},
 "error": null}

At most 1,000 rows per request. Send every column you know: left-out columns count as unknown, which makes the score less reliable. A record without an id column gets its position as entity_id.

Score from your data

curl -s -X POST "$P/runs/$MODEL_ID/predict" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"since": "2026-10-01", "until": "2026-10-31", "top": 100}'
Field
top How many to return, highest first (default 200, at most 2,000)
since, until Event models: a date window (YYYY-MM-DD, inclusive)
since_days Event models: the last N days
cutoff Forecast models: forecast as of this date instead of the latest data
entity_contains Only entities whose id contains this text
filters [{"column": "city", "op": "eq", "value": "Milano"}]; op is eq, ne, in, contains, gt, gte, lt or lte
include Extra columns to return with each prediction, under context
calibrated true for calibrated probabilities, where the model has a calibrator
new_rows Rows to add to the model's data for this call only, by table: {"orders": [{...}, ...]}. For example the coming days of a forecast (promotions, holidays), or history newer than the database. Never saved

To fill a form or a picker: GET /runs/{id}/record-fields lists the fields a record needs (required, optional), and GET /runs/{id}/entities the entity ids a model knows.

The response adds kind, meaning, count (all that matched) and showing; forecasts add as_of; an empty event-model result adds a note. See Make predictions for what each means.

Build a model

These need a Full access token. Planning and training run in the background: start them, then poll.

1. Connect your data

Files:

curl -s -X POST "$P/connections/from-csv" -H "$AUTH" \
  -F name="Telco customers" -F files=@telco.csv

Repeat -F files=@... for several tables.

Or a Postgres database (read-only user recommended), then start reading it:

curl -s -X POST "$P/connections" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Sales", "kind": "postgres", "config": {"dsn": "postgresql://readonly:pw@db.acme.com/sales"}}'
curl -s -X POST "$P/connections/$DATA_ID/introspect" -H "$AUTH"

Then poll until status is ready (or error):

curl -s "$P/connections" -H "$AUTH"

2. Ask the question

curl -s -X POST "$P/connections/$DATA_ID/opportunities" -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"mode": "single", "user_context": "Which customers will churn?"}'

The answer has a job_id. Poll GET /connections/$DATA_ID/opportunities/job until that job's state is done (or failed, with a message), then take the new question from GET /connections/$DATA_ID/opportunities.

3. Plan

curl -s -X POST "$P/opportunities/$QUESTION_ID/spec" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{}'

Poll GET /opportunities/$QUESTION_ID/spec until spec is no longer null. If planning failed, GET /opportunities/$QUESTION_ID has last_generation_error. The plan's id is what you train.

To change it in plain words: POST /opportunities/$QUESTION_ID/spec/refine with {"message": "Don't use the support_tier column"}, then poll for a higher version.

4. Train

curl -s -X POST "$P/runs" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"spec_id": "'"$PLAN_ID"'", "preset": "full_quality"}'

preset is full_quality (default) or fast_preview (a quick check on a sample). Poll GET /runs/$MODEL_ID until state is SUCCEEDED, FAILED (with error_code, error_message and suggestions) or CANCELLED. Step-by-step progress is at GET /runs/$MODEL_ID/events.json; POST /runs/$MODEL_ID/cancel stops it.

Your account

curl -s "$P/account" -H "$AUTH"
{"data": {"email": "you@example.com", "plan": "...", "llm_source": "managed",
          "credits": {"balance": ..., "costs": {...}},
          "predictions_this_month": ..., "predictions_monthly_limit": ...,
          "models_kept": ..., "models_limit": ..., "schedules": ...}, "error": null}

Polling

Poll every 2 to 5 seconds. Planning usually takes one to a few minutes; training from seconds to tens of minutes, depending on the data. Requests time out after 15 minutes, so never hold one open waiting: start the job, then poll.