Timestral API Guide: CSV In, 21 Quantiles Out

The web studio is for one-off forecasts. The API is for production: a server-to-server call that takes a CSV and returns the median, the 80% band and the full quantile CSV.

This guide is the contract: authentication, request shape, response shape, credits and failure behavior.

CSV forecast studio

Paste a series, get a probabilistic forecast.

One value per row, or a date column plus one or more numeric columns. Timestral returns a median forecast and a likely range. The demo runs on the public Hugging Face Space; the API is the paid product.

1 · Paste or upload a CSV2 · Pick a horizon3 · Download the 21 quantiles

Upload CSV

Steps

Airline passengersMonthly salesWebsite visitsElectricity load

month,passengers 1949-01-01,112 1949-02-01,118 1949-03-01,132 1949-04-01,129 1949-05-01,121 1949-06-01,135 1949-07-01,148 1949-08-01,148 1949-09-01,136 1949-10-01,119 1949-11-01,104 1949-12-01,118 1950-01-01,115 1950-02-01,126 1950-03-01,141 1950-04-01,135 1950-05-01,125 1950-06-01,149 1950-07-01,170 1950-08-01,170 1950-09-01,158 1950-10-01,133 1950-11-01,114 1950-12-01,140 1951-01-01,145 1951-02-01,150 1951-03-01,178 1951-04-01,163 1951-05-01,172 1951-06-01,178 1951-07-01,199 1951-08-01,199 1951-09-01,184 1951-10-01,162 1951-11-01,146 1951-12-01,166

↗Run forecast1 credit per API call · the web demo is free while the public Space is available

Authentication

Create a key at /settings/apikeys after signing in. Send it as a bearer token:

Authorization: Bearer sk_...

The key is tied to your account and its credit balance. Treat it like a password. Do not put it in client-side code, a public repo or a browser extension.

Request

POST /api/forecast
Content-Type: application/json
Authorization: Bearer sk_...

{
  "csv": "date,sales\n2026-01-01,120\n2026-01-02,135\n...",
  "steps": 12
}

• csv — the series, with an optional date column and up to 8 numeric columns. At least 8 rows. Maximum 2 MB.
• steps — the horizon, 1–1,024. The studio UI caps the default at 36 for speed.

Response

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "…",
    "columns": ["sales"],
    "rows": [
      {
        "time": "2026-02-01",
        "column": "sales",
        "low": 118.2,
        "median": 132.4,
        "high": 148.9
      }
    ],
    "took": "Took 2.97 s",
    "fileUrl": "https://timestral.org/api/media/uploads/forecast-….csv"
  }
}

• rows is the median and the 80% band for the first numeric column per time step.
• fileUrl is the full 21-quantile CSV, copied to our bucket so it does not expire with the model host.
• taskId is the ledger id. Use it in support requests.

Credits

One successful forecast costs one credit. The credit is charged before the model call and refunded automatically if the call fails. A failed call does not consume a credit.

The API returns insufficient_credits when the balance is empty. Buy a pack or a subscription from /pricing.

Errors

| Code | Meaning | | ---------------------- | ----------------------------------------------------------- | | Unauthorized | Missing or invalid API key | | invalid_csv | Empty, too large, or unparseable CSV | | too_few_rows | Fewer than 8 rows | | no_numeric_column | No numeric series found | | too_many_columns | More than 8 numeric columns | | invalid_steps | Horizon outside 1–1,024 | | insufficient_credits | No credits left | | quota_exceeded | The public model host is over quota; the credit is refunded | | forecast_failed | The model call failed; the credit is refunded |

A minimal client

curl -sS https://timestral.org/api/forecast \
  -H "Authorization: Bearer $TIMESTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv":"date,sales\n2026-01-01,120\n2026-01-02,135\n2026-01-03,128\n2026-01-04,141\n2026-01-05,150\n2026-01-06,162\n2026-01-07,155\n2026-01-08,168\n","steps":6}'

Production notes

• Idempotency. The API is metered per call. If your client retries, use your own idempotency key and check the taskId; do not fire the same request twice on a timeout.
• Quota. The public demo runs on a Hugging Face Space with a ZeroGPU quota. The paid API is intended for a dedicated quota; if the public host is exhausted, the call returns quota_exceeded and refunds the credit. This is a beta limitation, not a silent failure.
• Data retention. The CSV is used for the forecast you requested. The result is stored against your task so you can download it; the input is not used to train a model.
• Rate limits. The endpoint is rate-limited per IP and per key. Batch responsibly; use the small model for high-volume scoring.

What to read next

• What is Timestral? — the model family.
• How to format a CSV for Timestral — the input contract.
• How to evaluate forecasts — backtesting.
• API pricing — credits and plans.

FAQ

Can I use the API without an account?

No. The API key is tied to an account and a credit balance. The web demo is the no-account path.

Is the API synchronous?

Yes. The request returns when the forecast is ready, or with an error. For large batches, run requests in parallel with client-side concurrency limits.

What happens if the model host is down?

The call returns an error and the credit is refunded. The task row records the failure so support can trace it.

Can I get a dedicated endpoint?

The paid API is intended for a dedicated quota. Contact contact@timestral.org for volume or a private endpoint.