TSFM.ai developer documentation.

Multiple pages, one contract. API, MCP, and CLI are aligned on the same schema so teams can move from manual calls to production automation with zero drift.

Forecast Contract

Canonical request shape for TSFM inference

Canonical shape is { model, inputs, parameters }. Compatibility aliases remain accepted for migration, but new integrations should standardize on canonical fields for predictable behavior.

forecast.request.json

Try in Playground

{
  "model": "google/timesfm-2.5",
  "inputs": [{
    "item_id": "sku_42",
    "start": "2026-01-01",
    "target": [110, 113, 108, 116, 119, 121],
    "past_covariates": {
      "promo": [0, 1, 0, 1, 1, 0]
    },
    "future_covariates": {
      "promo": [1, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 0]
    }
  }],
  "parameters": {
    "prediction_length": 12,
    "freq": "D",
    "quantiles": [0.1, 0.5, 0.9]
  }
}

forecast.response.json

{
  "id": "forecast_7af1e2",
  "model": "google/timesfm-2.5",
  "provider": "metis-tsfm",
  "predictions": [{
    "item_id": "sku_42",
    "mean": [122.0, 123.3, 124.1, 124.8, 125.4, 126.0, 126.8, 127.4, 128.0, 128.9, 129.4, 129.9],
    "quantiles": {
      "0.1": [119.4, 119.8, 120.6, 121.0, 121.7, 122.1, 122.6, 123.0, 123.6, 124.0, 124.5, 124.8],
      "0.5": [122.0, 123.3, 124.1, 124.8, 125.4, 126.0, 126.8, 127.4, 128.0, 128.9, 129.4, 129.9],
      "0.9": [125.2, 126.9, 127.7, 128.8, 129.6, 130.2, 131.3, 132.0, 132.9, 133.6, 134.2, 134.8]
    }
  }],
  "usage": {
    "input_tokens": 188,
    "output_tokens": 36,
    "prompt_tokens": 188,
    "completion_tokens": 36,
    "total_tokens": 224
  },
  "latency_ms": 51
}

Top-level request fields

Field	Type	Required	Description
model	string	Yes	Catalog model id, e.g. `amazon/chronos-2`. See `/api/models` for available models.
inputs	array<object>	Yes	One or more series payloads. Preferred canonical shape for TSFM requests.
parameters	object	No	Forecast controls (`prediction_length`, `freq`, `quantiles`) and model knobs.
metadata	object	No	Opaque passthrough metadata for client traceability.

Input series object (`inputs[]`)

Field	Type	Required	Description
item_id	string	No	Series identifier echoed in response for joins and merges.
start	string (ISO date/time)	No	Anchor timestamp for generated forecast timeline.
target	number[]	Yes	Historical observations used as model context.
past_covariates	record<string, number[]>	No	Observed exogenous signals aligned with `target` history.
future_covariates	record<string, number[]>	No	Known future exogenous signals aligned with horizon.

Parameters object

Field	Type	Required	Description
prediction_length	integer	No	Number of future points to generate. Defaults to 12 when omitted.
freq	string	No	Sampling frequency (`D`, `H`, `15min`, etc.) used for timeline interpolation.
quantiles	number[]	No	Requested quantiles in ascending order, typically `[0.1, 0.5, 0.9]`.
sensitivity	number	Conditional	Anomaly threshold for `/v1/detect-anomalies` (higher means fewer anomalies).

Response fields

Field	Type	Required	Description
predictions	array<object>	Yes	Forecast outputs per series with mean + quantile trajectories.
usage	object	Yes	Token accounting used by usage/billing dashboards.
latency_ms	number	Yes	Observed server latency for the request.
timeline	string[]	No	Compatibility alias timeline for simpler plotting in clients/playground.

Compatibility aliases

Existing integrations can keep legacy keys while migrating. The server normalizes aliases into canonical fields.

horizon / h / prediction_length
freq / frequency / granularity
quantiles / quantile_levels / levels
target / values / past_values / series
timestamps / history are normalized into timeline-compatible metadata

Anomaly detection request

/v1/detect-anomalies reuses the same canonical series structure. Include parameters.sensitivity to tune the threshold for anomaly flags.

detect-anomalies.request.json

{
  "model": "cmu/moment-large",
  "inputs": [{
    "item_id": "sensor_7",
    "target": [20.1, 20.3, 20.4, 20.2, 20.5, 27.8, 20.6, 20.7]
  }],
  "parameters": {
    "sensitivity": 2.0
  }
}

Batch forecast request

/v1/forecast/batch accepts an array of forecast jobs. Each entry can target a different model.

forecast-batch.request.json

{
  "requests": [
    {
      "model": "amazon/chronos-2",
      "inputs": [{ "item_id": "north", "target": [10, 11, 12, 13, 14] }],
      "parameters": { "prediction_length": 6, "freq": "D" }
    },
    {
      "model": "google/timesfm-2.5",
      "inputs": [{ "item_id": "south", "target": [6, 7, 8, 9, 10] }],
      "parameters": { "prediction_length": 6, "freq": "D" }
    }
  ]
}

Playground file ingest formats

Local files and URL sources are normalized by /v1/series/ingest before dispatch.

Field	Type	Required	Description
CSV	text/csv	No	Columns: `timestamp`, `value`, optional `item_id`, optional covariate columns.
JSON array	application/json	No	Records like `{ timestamp, value, item_id? }` or canonical `inputs[]` payload.
NDJSON	application/x-ndjson	No	One observation per line for large uploads and stream transforms.

Quality checks before production use

Validate model horizon limits and context window limits per model card.
Backtest with sliding windows before turning on automatic forecast consumption.
Store request ids and full parameters for reproducibility.
Watch quantile calibration drift in monitoring dashboards.