docs

API documentation

Reference

Find error codes, input limits, rate limits, and usage details.

Error codes

All errors share a common envelope. The request_id matches the one in usage logs — include it when contacting support.

Error response
{
  "error": {
    "code": "invalid_request",
    "message": "horizon: Input should be less than or equal to 512",
    "request_id": "req_a1b2c3d4e5f67890a1b2c3d4e5f67890"
  }
}
HTTPCodeDescription
400invalid_requestSchema, value, or limit violation in the request body
401unauthorizedMissing, invalid, or revoked API key
402payment_requiredInsufficient credits
403forbiddenInsufficient permissions
404not_foundUnknown route
405method_not_allowedHTTP method not allowed for this route
408request_timeoutRequest body was not received within 15 seconds
413payload_too_largeRequest body exceeds the size limit
429rate_limitedRate limit exceeded — retry with backoff
500internal_errorUnexpected server error
503model_unavailableModel is not available — retry later
504timeoutInference timed out

If an error does not resolve, see Help. opens in a new tab

Input limits

Requests exceeding these limits are rejected with 400 invalid_request.

LimitValue
Points per series16–2048
Series per requestup to 64
Forecast horizon1–512
Total input points per requestup to 131,072

Rate limits

Applied per API key with a token bucket: burst of 10 requests, refilling at 1 request/sec (free tier). Exceeding it returns 429 rate_limited.

CSV upload format

The CSV accepted by "Try your data" in the Playground and the result CSV it returns. Same columns as the specimen on that screen.

ItemDetails
FileComma-separated. UTF-8 or Shift_JIS. Up to 10 MB
Row 1Header row. Column names are free-form (duplicates become _2, _3, …)
Column with dates or timesOne column (inferred; optional). ISO 8601 date-time or date only. A date-time without an offset is read as the browser's local time. If rows are evenly spaced, future timestamps are filled in on the result
Value columnsNumbers only; no empty cells or Infinity. Selecting several forecasts them jointly as one multivariate task (sent with a group)
Limits16–2048 rows, up to 64 value columns. Same as the API input limits
HandlingThe file is read in the browser; only the selected numeric columns are sent to the server. Nothing is stored
Example input CSV
timestamp,building_a_kw,building_b_kw,building_c_kw
2014-11-18T01:00:00Z,153.1,98.5,417.7
2014-11-18T02:00:00Z,148.1,97.1,387.1
2014-11-18T03:00:00Z,100.7,99.6,375.3
Example result CSV (tail)
timestamp,type,building_a_kw,building_b_kw,building_c_kw
2015-01-01T00:00:00Z,actual,71.8,72.2,299.8
2015-01-01T01:00:00Z,forecast,127.6,110.6,434.2
2015-01-01T02:00:00Z,forecast,130.7,76.2,347.2

The result CSV lists actual rows followed by forecast rows, distinguished by the type column (actual / forecast). Forecast timestamps extend the input interval. Date-only columns stay date-only, and date-times with seconds and a Z keep that format; all other date-times use UTC ISO 8601. Forecast rows also use UTC for offset-less inputs so that times remain distinct across daylight-saving transitions. Actual rows keep their original values. Cells starting with = + - @ are quoted so they are not executed as formulas.

Usage

The usage object in every 200 response shows how many data points the request consumed. The same numbers appear in the request log on the Usage page.

FieldDescription
input_pointsTotal input points across all submitted series
output_pointsTotal points returned. Defined per endpoint: forecast = horizon × series count / anomaly = sum of 2 × (length − test_start) / impute = sum of imputed (null) points / embed = 0
series_countNumber of series in the request