API reference

Base URL and authentication

https://api.nums.world

Send your API key in either of these headers. Use an existing API key. See API access for availability and support.

Authorization: Bearer csl_...
X-Causilo-Key: csl_...

Routes

There is no route for cancelling a prediction. A request you abandon runs to the end and is counted in full, as Limits explains. POST /v1/cancel answers 501, which tells a client that calls it that the feature does not exist.

Sending a prediction

The Python client builds the request for you, and the quickstart shows one classification call and one regression call made with it. Callers who do not use the client send the request below.

POST /v1/predict takes a multipart body with three parts: context and query as Parquet (application/vnd.apache.parquet), and params as JSON. A single Parquet file is accepted as well, carrying the same JSON in its causilo-params schema metadata, in which case the rows whose target is missing are treated as the query.

Feature columns must appear in both tables with the same names and in the same order, because the model reads them by position.

What a column may hold

Each kind of column is handled as follows. Every refusal is a 422 response whose detail names the column.

The same column must hold the same kind of value in both tables. A context in which every feature column holds a single value is refused, since there is nothing in it to predict from.

What the target column may hold

The target column is present in the context and absent from the query. In a single Parquet file, the rows with an empty target are the rows to predict.

params

Storing a context with cache_context and naming it later with context_id saves the upload but not the cells, as the One table, many questions example measures.

Fields that are not listed here are ignored, so a caller moving from another API does not have to remove its own options first.

output_type

What comes back

prediction holds one value per query row. metadata carries the shape of the request, the elapsed time, quota and served_by, which identifies the image, the checkpoint and the ensemble width that produced the numbers. When you compare predictions across runs, compare served_by first.

Response fields

Limits

For api.nums.world · Verified Oct 21, 2026 (UTC). Other deployments may differ.

All limits apply together; the maximum row and feature counts cannot necessarily be used in the same request.

curl --fail --silent --show-error https://api.nums.world/v1/limits

Account allowance

Your account has a daily and a monthly allowance of cells and limits on requests per minute and per hour. Use your API key with GET https://api.nums.world/v1/usage to check usage and allowances for that credential, and every successful response carries them in metadata.quota. When an allowance runs out the service answers 429 until it resets. Nothing is invoiced and there is no overage.

Asking about your own table

GET https://api.nums.world/v1/estimate tells you whether a table of your shape will be accepted. It needs no key, uploads nothing and runs the same checks as admission control, so its verdict is the one a real request would get.

curl 'https://api.nums.world/v1/estimate?n_context=300000&n_query=1000&n_features=10'

{
  "accepted": false,
  "cells": 3010000,
  "counts_against_allowance": 3010000,
  "estimated_seconds": 99.1,
  "model": "causilo-clf",
  "deadline_s": 300.0,
  "max_context_rows": 299000,
  "code": "request_too_large",
  "reason": "301,000 rows is over the 300,000 row limit."
}

Everything in the answer except the cell count, which is exact, is a prediction from a fitted model. max_context_rows is the number of context rows that fit at your column count, which is the figure a refusal would have named. When a shape is refused, reason gives the same explanation the refusal would give.

How requests are counted

A cell is one value in a table you send, counting the context and query rows together and excluding the target column. A request that names a stored context is counted for the context rows as well, because storing a context saves the upload and not the cells.

A request refused before it runs, whether by validation, a limit or a rate limit, uses no cells, and neither does one whose response is too large to return. It still counts towards the requests per minute and per hour, as every request that reaches the service does. A request that ran and then failed uses its cells; these are the 504 and the 502 described under Errors.

A request you abandon is also counted in full. Disconnecting does not reach the machine running the prediction, which finishes the work regardless, and a call that has started cannot be cancelled, which is why POST /v1/cancel answers 501. The Python client reports this case as CausiloTimeout and does not retry, since a retry would be counted again, so give it a timeout long enough to read the answer the request has already used cells for.

Cell accounting and recovery

Cell cost: (n_context + n_query) * n_features. Feature columns exclude the target. Reusing a stored context still counts its rows; the saving is the upload.

POST /v1/cancel returns 501; a started request cannot be stopped. Requests refused before work still count towards request-rate limits.

Client wall-clock time also includes the network round trip.

Sending more than one call at a time

The rate limits are not a parallelism budget. Calls beyond what the service is running at the moment are queued and answered in turn, so none is refused for being concurrent, and the time spent waiting appears as latency.

Sending calls in parallel helps when tables are small and makes little difference when they are large, because large calls wait for the same GPU in turn. Many small queries against one table are faster as a single call with more query rows than as many calls.

A large table also delays the calls queued behind it, since it holds the queue for as long as it runs. Where latency matters, keep tables small and store the context instead of sending it again.

elapsed_s in the response measures the prediction alone and excludes the time the call spent queued, so a client measuring wall-clock time will see a larger number. The difference between the two is the time spent in the queue.

Errors

Errors are RFC 9457 problem documents, and you should branch on code. The status appears in the body as well as on the response. Every error carries a request_id, which is also sent as the X-Request-Id header, and a retryable boolean that says whether sending the same request again can succeed. A 429 or 503 response also carries Retry-After in whole seconds. Successful responses carry X-Request-Id too, in the header only.

Two statuses mean that the work has already run. A 504 with code timeout means the service stopped waiting while the prediction continued to the end, and it is counted in full. A 502 with code upstream_unavailable means the prediction ran but its answer could not be read. Both carry retryable: false, because a second attempt would be counted again, so send a smaller table instead. The Python client never retries either of them, whatever the body says.

The type of every error links to its row in the table below. The Python client raises one exception class for each group of codes, and the Usage, limits and cancellation example lists which class covers which codes.