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.
Playground
Interactive sandbox for time series inference
The Playground is a browser-based workbench for running forecasts, anomaly detection, classification, imputation, and batch jobs against any model in the catalog. No code, no API keys required for guest mode—just paste data and hit Run.
Available tasks
Each task maps to a dedicated API endpoint. Task availability depends on the selected model's capabilities.
| Field | Type | Required | Description |
|---|---|---|---|
| Forecast | /v1/forecast | Yes | Generate point and quantile predictions for one series. Configure horizon (1-512), frequency, context length (4-4096), and quantiles. |
| Anomaly Detection | /v1/detect-anomalies | Yes | Detect anomalous observations using z-score thresholds. Tune sensitivity (1.5-6.0) and window size (4-128). Requires 8+ data points. |
| Classification | /v1/classify | Yes | Assign time series to classes with confidence scores. Configure number of classes (2-20) and optional custom labels. |
| Imputation | /v1/impute | Yes | Fill missing values (blank cells or NaN) in a series using model-based interpolation. No extra parameters needed. |
| Batch Forecast | /v1/forecast/batch | Yes | Run up to 10 forecast jobs in one request (64 max via API). Each job can target a different model, horizon, and frequency. |
Getting data in
Every task tab includes a series input area that accepts three input methods.
Paste or type
Enter CSV rows directly in the textarea. Format: one timestamp,value pair per line. The first line can be a header row.
Upload a file
Drag or browse for .csv, .tsv, .txt, or .json files. The parser auto-detects format and extracts timestamp + value columns.
Load from URL
Paste a public URL to a CSV or JSON file. The Playground fetches and normalizes the data through the /v1/series/ingest endpoint.
Supported file formats
Uploaded files and URL sources are normalized by the parser before being sent to the inference endpoint.
| 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. |
Loading data from external URLs
The “Load URL” feature fetches remote data through the /v1/series/ingest endpoint, which normalizes CSV, JSON, and NDJSON sources into the canonical series format.
Requirements
- The URL must be publicly accessible (no auth headers are forwarded).
- Supported content types:
text/csv,application/json,application/x-ndjson,text/plain. - CSV files must have
timestampandvaluecolumns. Additional columns (item_id, covariates) are preserved. - JSON files can be arrays of objects, numeric arrays, tuple arrays, or the canonical
inputs[]payload shape.
Troubleshooting URL loads
- If the URL returns HTML instead of data, check that it points to the raw file (e.g. use GitHub raw URLs, not blob pages).
- CORS-restricted URLs will fail. The ingest endpoint fetches server-side, so most public URLs work.
- Very large files may time out. Pre-trim to the most recent data window before loading.
Parameter limits
Enforced in the Playground UI. API limits may differ—see the API Reference for authoritative constraints.
| Field | Type | Required | Description |
|---|---|---|---|
| Horizon | 1 – 512 steps | Yes | Number of future data points to forecast. Default is 16 in Playground, 12 via API. |
| Context length | 4 – 4,096 points | No | Optional cap on how many historical points the model sees. When omitted the full series is used. |
| Series minimum | 4+ points (8+ for anomaly) | Yes | Minimum data points required per series. Anomaly detection requires at least 8. |
| Batch series | 10 UI / 64 API | No | Playground limits batch jobs to 10 cards. The raw API accepts up to 64 per request. |
| Sensitivity | 1.5 – 6.0 | No | Z-score threshold for anomaly detection. Higher values flag fewer anomalies. Default 2.5. |
| Window size | 4 – 128 | No | Rolling window for anomaly z-score calculation. Default 12. |
| Quantiles | 0 – 1 (comma-separated) | No | Forecast quantile levels. Default: 0.1, 0.5, 0.9. Values must be ascending. |
| Classes | 2 – 20 | No | Number of classification buckets. Custom labels can be provided as comma-separated names. |
Guest mode
No account needed
- Stricter rate limits and payload size caps.
- Guest consent clickwrap may be required (environment-dependent).
- Submitted data may be used for model training per the data-use policy.
- Run history is stored locally in session storage only.
Authenticated
Sign in for full access
- Higher rate limits and larger payloads.
- Usage tracked against your account for billing visibility.
- Token and cost telemetry displayed per run.
- Same API key works in Playground, CLI, MCP, and direct HTTP.
Export formats
Download results from the forecast panel after a successful run.
| Field | Type | Required | Description |
|---|---|---|---|
| JSON | Download | No | Full API response including predictions, usage, latency, and metadata. |
| CSV | Download | No | Tabular export with step, timestamp, point forecast, and quantile columns. |
| Chart PNG | Download | No | Rendered time series chart with historical data and forecast overlay as an image. |
Task-specific guidance
Forecast
The default task. Provide at least 4 historical data points with timestamps and values. Adjust prediction_length (horizon) to control how far ahead the model forecasts. Use quantiles to get uncertainty bands—the wider the spread between 0.1 and 0.9, the more uncertain the model is. Set frequency to match your data cadence (D for daily, H for hourly, 15min for sub-hourly).
Anomaly Detection
Requires at least 8 data points. The detector uses a rolling z-score window to flag outliers. Lower sensitivity (e.g. 1.5) catches more anomalies; higher values (e.g. 5.0) flag only extreme spikes. The window size controls the rolling calculation window—larger windows smooth noise but may miss local events. Results include severity labels (high, medium, low) based on z-score magnitude.
Classification
Set the number of target classes (2–20) and optionally name them with comma-separated labels. The model assigns each series a predicted class with a confidence score and probability distribution across all classes. Useful for categorizing patterns like “trending up”, “seasonal”, or “stationary”.
Imputation
Mark missing values by leaving cells blank or entering NaN in the series input. The model fills gaps using surrounding context. No extra parameters needed. Results highlight which values were imputed vs. original data. Best for patching sensor dropouts or incomplete records.
Batch Forecast
Add up to 10 series cards, each with its own data and optional per-series horizon and frequency. Defaults apply to all cards unless overridden. The batch is submitted as a single API call. Results show per-series success/failure status with expandable charts and tables. Failed series don't block successful ones—partial results are always returned.
Tips and best practices
Start with the defaults
Each task tab opens pre-loaded with sample data. Hit Run to see a result instantly before swapping in your own series.
Watch the telemetry grid
Every run shows input points, horizon, tokens consumed, estimated cost, latency, and HTTP status. Use this to tune cost vs. accuracy.
Use run history
The last 60 runs per task are stored in session storage. Compare models, horizons, and parameters without re-running queries.
Deep-link to settings
Model and task are synced to URL params (?model=amazon/chronos-2&task=anomaly). Share links to reproduce exact Playground states.
Download results
Export forecast results as JSON (full response), CSV (tabular), or chart PNG (rendered visualization) from the results panel.
Check model support
Not every model supports every task. Unsupported task tabs are automatically disabled when you select a model.
URL parameters
Playground state is persisted in the URL for easy sharing and bookmarking.
| Param | Example | Description |
|---|---|---|
| model | amazon/chronos-2 | Pre-selects a model from the catalog sidebar. |
| task | anomaly | Opens a specific task tab. Values: forecast (default), anomaly, classify, impute, batch, coming-soon. |
Next steps
Ready to move beyond the Playground? Use the same payload shape across all integration surfaces.