# Time Series Forecasting (Chronos-2): Sales, Demand, Traffic (`jumblemog/time-series-forecasting`) Actor Forecast sales, demand, traffic, prices or any time series with Amazon's Chronos-2 model: prediction intervals, backtest accuracy, seasonality, a plain-language summary and a chart per series. From values, CSV, Excel, Google Sheets or an Apify dataset. For AI agents. - **URL**: https://apify.com/jumblemog/time-series-forecasting.md - **Developed by:** [Jumble Mog](https://apify.com/jumblemog) (community) - **Categories:** AI, E-commerce, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Time Series Forecasting (Chronos-2): Sales, Demand, Traffic **Forecast any time series with Amazon's Chronos-2 model, with no training or tuning.** Give it sales, demand, web traffic, prices, energy use, sign-ups or sensor readings, as a list of numbers, JSON rows, CSV, a link to a CSV, Excel file or Google Sheet, or an Apify dataset. Every series gets a forecast with **prediction intervals, a backtest of its accuracy on its own recent past, its seasonal pattern, a summary in plain words and a chart**. Dates, time steps, separate series and gaps are worked out from the data, and what you already know about the future (planned promotions, prices, public holidays) is used by the model. Made for analysts, e-commerce and operations teams, automations and AI agents that need a forecast they can check from one API call. ![Two forecasts made by this Actor: the monthly CO₂ record of Mauna Loa with its yearly cycle continued two years ahead inside shaded 80% and 95% intervals, and daily units sold at a store with a weekly pattern, promotion peaks in the forecast and an unusual drop marked with a red dot](https://api.apify.com/v2/key-value-stores/Km5b4PG3kYHdZSb1E/records/time-series-forecasting-examples.png?signature=yCGkhSGC6W4C9kInvucN) ### What it does - **Forecasts from a foundation model**: [Chronos-2](https://huggingface.co/amazon/chronos-2) is Amazon's open forecasting model (Apache-2.0, 120 million parameters), pretrained on a large collection of time series. Amazon reports state-of-the-art zero-shot accuracy among public models on the fev-bench, GIFT-Eval and Chronos Benchmark II benchmarks. It runs inside the Actor, so your data isn't sent to any other service, and it needs no training: one series of a dozen values or thousands of series with years of history work the same way. - **Prediction intervals**: the ranges the actual values should fall in, 80% and 95% by default or any levels you choose, and any extra quantiles (such as q90 for a 90% service level in stock planning). - **A backtest on your own data**: each series is also forecast from its earlier history and checked against what really happened, with MAE, RMSE, MAPE, sMAPE, WAPE and MASE, how much better it did than simply repeating the last cycle, and how often the intervals held the actual values. You see how far to trust each forecast before you use it. - **Covariates and known future values**: columns such as promotion, price, temperature or events help the model. Add rows for future dates with the value left empty and the covariates filled in (a promotion planned for next Friday), and the forecast uses them. Public holidays of a country or region (`US`, `GB`, `DE-BY`, `IN`) can be added with one setting. - **Many series in one run**: long data (one row per date and store, product or ticker) is split into series by itself, and so is wide data (one column per series). Up to 5,000 series per run, forecast in batches. - **Any time step**: minutes, hours, days, business days, weeks, months, quarters (fiscal ones too) and years. Irregular events such as orders, posts or sign-ups are put on a daily, weekly or monthly grid and added up, averaged or counted. Gaps are left for the model, which handles missing values itself. - **Seasonality and change**: the strongest repeating pattern (daily, weekly, yearly) with when it peaks ("highest on Saturdays", "in May"), and how the forecast compares with the previous period and with the same period a year earlier. - **Unusual values**: an optional check of the history for spikes, drops and data errors, each listed with the range the model expected. - **A summary in plain words** for every series, ready for a report, a Slack message or an AI agent's answer. - **Charts**: the history, the forecast and its intervals in one clean chart per series, as PNG, SVG, PDF or an interactive HTML page. - **Tables and JSON**: each forecast step as a row in the dataset's Forecast view and in `forecast.csv`, and every forecast as JSON in the run's `OUTPUT`, so the `run-sync` API endpoint answers with them directly. ### Who it's for - **E-commerce and retail**: demand and sales per product or store for stock and staffing, with promotions and holidays. - **Finance and analysts**: revenue, costs, orders and KPIs by month or quarter, with a range instead of a single number. - **Marketing, SEO and product teams**: web traffic, sign-ups, installs, search interest and ad spend. - **Operations and energy**: call volumes, support tickets, deliveries, electricity load and sensor readings at hourly or 15-minute steps. - **AI agents and LLM apps**: language models are poor at extrapolating numbers. An agent can send a list of values and get back a calibrated forecast, its accuracy and a summary to pass on. - **Apify users**: forecast what your scrapers collect over time, such as prices, reviews per day, followers or search interest, straight from a run's dataset. ### How to use it 1. Put your data in **Data rows**, **Values**, **Several series**, **CSV data**, a **Data file link** or an **Apify dataset**. The form starts with five years of monthly CO₂ readings, so you can click **Start** right away to see a result. 2. Set **Steps to forecast** if you like, or leave it for a sensible default (12 months, 30 days, 13 weeks...). Columns, time step and series are found by themselves; set them when the guess is wrong. 3. Click **Start**. The **Overview** shows each series with its chart, summary and accuracy, and the **Forecast** view every forecast step with its intervals. You can also run it through the [Apify API](https://docs.apify.com/api/v2), on a schedule, or from Make, n8n, Zapier and other integrations. ### How-to examples #### How to forecast monthly sales from a list of numbers ```json {"values": [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118, 115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140], "startDate": "2024-01", "seriesName": "Monthly sales", "horizon": 12} ``` Result: the next 12 months, each with a forecast and 80% and 95% intervals, a chart, and a `summary` written in plain words, such as "Forecast for the next 12 months (...): 193 per month on average, 2,311 in total, 13.2% more than the previous 12 months... The history has a strong yearly pattern, highest in July and lowest in November." A backtest on the last months says how far off the model was on your own data. #### How to forecast a CSV file or Google Sheet ```json {"dataUrl": "https://github.com/datasets/co2-ppm/blob/main/data/co2-mm-mlo.csv", "valueFields": ["Average"], "horizon": 24} ``` Result: 24 months of CO₂ readings forecast from NOAA's record since 1958. The date column and the monthly step are found by themselves. A public Google Sheet link works the same way. #### How to forecast demand for many products at once ```json {"series": [{"name": "SKU-1001", "values": [12, 15, 11, 18, 14, 16, 13, 19, 15, 17], "startDate": "2025-08-04", "frequency": "week"}, {"name": "SKU-1002", "values": [4, 0, 6, 3, 5, 2, 7, 4, 3, 6], "startDate": "2025-08-04", "frequency": "week"}], "horizon": 8, "intervals": [50, 90], "quantiles": [0.95], "crossLearning": true} ``` Result: one item per product with 8 weekly forecasts, the 50% and 90% intervals and the 95% quantile, which is the stock level that covers demand 19 weeks in 20. `crossLearning` lets short, related series learn from each other. Up to 1,000 series fit in one run, or rows in long format with `seriesFields` such as store and product. #### How to let an AI agent forecast numbers Add this Actor to the [Apify MCP server](https://mcp.apify.com) with `https://mcp.apify.com/?tools=jumblemog/time-series-forecasting`. Language models are poor at extrapolating numbers, so the agent sends the values and passes on the `summary`, the forecast and its accuracy instead of guessing. ### FAQ **Do I need to train a model?** No. Chronos-2 is a pretrained forecasting model, so it forecasts any series straight away, with no training or tuning. **How accurate is it?** Every run says so for your data: the backtest forecasts the last part of the history from the part before it and reports the error (WAPE or MAPE) and how much better it did than repeating the last cycle. **Can it use promotions, prices or holidays?** Yes. Columns in `covariateFields` help predict the values, including their planned future values, and `holidays` adds a country's or region's public holidays. **Can it find anomalies?** Yes. `detectAnomalies` marks unusual values in the recent history. **Does it work with Zapier, Make or n8n?** Yes. Call the Actor with its Apify app or an HTTP request on a schedule, and send the summary or the chart on. ### Input | Field | What it does | | --- | --- | | `data` | Rows as JSON: `[{"date": "2025-01", "sales": 1200}, ...]`, long or wide, or an object of dates and values (`{"2025-01": 1200, ...}`). | | `values`, `dates`, `startDate`, `seriesName` | One series as a list of numbers, oldest first, with a date for each value or the date of the first one (`2025-01-01` daily, `2025-01` monthly, `2025-Q1` quarterly, `2025` yearly). Without dates the forecast counts steps. | | `series` | Named series, each with its own values and dates: `[{"name": "Store A", "values": [...], "startDate": "2025-01-01", "frequency": "day"}]`. A series can carry `covariates`, whose lists may run into the future. | | `csv`, `dataUrl`, `datasetId` | CSV or TSV text with a header row; a link to a public CSV, TSV, JSON or Excel (.xlsx) file, Google Sheet or GitHub file (up to 30 MB); or an Apify dataset (up to 500,000 items, including lists of dated items inside each item). | | `dateField`, `valueFields`, `seriesFields`, `covariateFields` | The date column, the columns to forecast, the columns that tell series apart (store, product, ticker) and the columns that help predict the values (price, promotion). Found by themselves except covariates; nested fields like `stats.views` work. | | `frequency` | `auto` (default), `minute`, `5min`, `15min`, `30min`, `hour`, `day`, `business day`, `week`, `month`, `quarter` or `year`. A coarser step than the data's adds values up or averages them per step. | | `aggregate` | How values in the same step combine: `auto`, `sum`, `mean`, `median`, `min`, `max`, `first`, `last`, or `count` to forecast the number of rows per step. | | `fillMissing` | Steps without data: `auto` (left as gaps, or 0 for counts and summed events), `leave`, `zero`, `previous` or `interpolate`. | | `horizon` | Steps to forecast, up to 1,024. Default: the future rows the data lists, or 48 hours, 30 days, 22 business days, 13 weeks, 12 months, 8 quarters or 5 years. | | `intervals`, `quantiles` | Prediction intervals in percent (`[80, 95]`), and extra quantiles between 0 and 1 (`[0.05, 0.9]`). | | `holidays` | A country or region code whose public holidays the model gets as a known covariate, for daily, business-day, weekly and hourly data. | | `nonNegative` | `auto` (no negative forecasts when the history has none), `yes` or `no`. | | `crossLearning`, `contextLength` | Let the model learn across all series of the run (for short related series), and limit how much recent history it reads (up to 8,192 steps). | | `backtest`, `backtestWindows` | The accuracy check (on by default) and how many past windows it tests (3, or 1 for runs of more than 100 series). | | `detectAnomalies` | Look for unusual values in the last 512 steps of each history. | | `chart`, `chartFormats`, `chartTheme`, `chartHistory`, `title` | Charts on or off, `png` (default), `svg`, `pdf` and `html`, `light` or `dark`, how many past steps to show, and the first chart's title. | | `maxCharts`, `maxSeries` | The most charts (25) and series (1,000; up to 5,000) per run. | The quickest forecast, a list of monthly values (made-up numbers): ```json { "values": [112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118, 115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140], "startDate": "2024-01", "seriesName": "Monthly sales", "horizon": 12 } ``` A CSV file from a link, choosing the column to forecast (NOAA's monthly CO₂ record since 1958): ```json { "dataUrl": "https://github.com/datasets/co2-ppm/blob/main/data/co2-mm-mlo.csv", "valueFields": ["Average"], "horizon": 24 } ``` Daily sales per store and product in long format, with planned promotions and Bavarian public holidays (shortened: real data would have months of rows). The rows for the coming days have no `units`, only the promotions, and the forecast covers those days: ```json { "data": [ {"date": "2025-06-01", "store": "Berlin", "product": "Espresso", "units": 41, "promo": 0}, {"date": "2025-06-01", "store": "Berlin", "product": "Latte", "units": 63, "promo": 1}, {"date": "2025-06-01", "store": "Munich", "product": "Espresso", "units": 28, "promo": 0}, "...", {"date": "2026-01-05", "store": "Berlin", "product": "Espresso", "units": null, "promo": 1} ], "covariateFields": ["promo"], "holidays": "DE-BY", "detectAnomalies": true } ``` A public Google Sheet with a date column and one column per product, 13 weeks ahead: ```json { "dataUrl": "https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit#gid=0", "frequency": "week", "horizon": 13 } ``` The items of a scraper run, such as one row per product and day with a price, forecasting the price of each product: ```json { "datasetId": "YOUR_DATASET_ID", "dateField": "scrapedAt", "valueFields": ["price"], "seriesFields": ["productId"], "frequency": "day" } ``` Several series at once, with the interval levels and quantiles a stock planner needs: ```json { "series": [ {"name": "SKU-1001", "values": [12, 15, 11, 18, 14, 16, 13, 19, 15, 17], "startDate": "2025-08-04", "frequency": "week"}, {"name": "SKU-1002", "values": [4, 0, 6, 3, 5, 2, 7, 4, 3, 6], "startDate": "2025-08-04", "frequency": "week"} ], "horizon": 8, "intervals": [50, 90], "quantiles": [0.95], "crossLearning": true } ``` ### Output Each series becomes one dataset item. This is the item for the first example above, shortened to two forecast steps: ```json { "series": "Monthly sales", "status": "ok", "error": null, "summary": "Forecast for the next 12 months (January 2026 to December 2026): 193 per month on average, 2,311 in total, 13.2% more than the previous 12 months. It goes from 170 in January 2026 (80% interval 160 to 180) to 187 in December 2026 (160 to 209). The history has a strong yearly pattern, highest in July and lowest in November. Backtest on the last 12 months: average error 17.3% (WAPE), 4% less error than repeating the previous year; the 80% interval held 75% of the actual values.", "frequency": "month", "horizon": 12, "historyStart": "2023-01-01", "historyEnd": "2025-12-01", "historyPoints": 36, "lastValue": 166, "nextValue": 169.637, "nextDate": "2026-01-01", "forecastMean": 192.558, "forecastTotal": 2310.69, "changePct": 13.2, "direction": "up", "backtestErrorPct": 17.26, "backtestMetric": "WAPE", "forecast": [ {"step": 1, "date": "2026-01-01", "period": "2026-01", "forecast": 169.637, "lower80": 159.796, "upper80": 180.201, "lower95": 142.623, "upper95": 192.466}, {"step": 2, "date": "2026-02-01", "period": "2026-02", "forecast": 179.878, "lower80": 168.191, "upper80": 190.779, "lower95": 149.419, "upper95": 202.361} ], "comparison": {"forecastMean": 192.558, "forecastTotal": 2310.69, "previousMean": 170.167, "previousTotal": 2042, "changePct": 13.2, "comparedWith": 12, "direction": "up"}, "seasonality": {"period": 12, "name": "yearly", "strength": 0.93, "high": "in July", "low": "in November"}, "backtest": {"windows": 1, "horizon": 12, "points": 12, "mae": 29.37, "rmse": 33.84, "mape": 16.43, "smape": 18.34, "wape": 17.26, "mase": 2.259, "naiveMae": 30.5, "improvementVsNaivePct": 3.7, "coverage80": 75, "coverage95": 100, "naiveMethod": "repeat the last 12 values"}, "unusualValues": null, "covariates": null, "nonNegative": true, "chartUrl": "https://api.apify.com/v2/key-value-stores//records/chart-0001-Monthly-sales.png", "notes": [] } ``` - `forecast` has one row per step with the median forecast, the interval bounds (`lower80`, `upper80`...) and any extra quantiles (`q95`). Weekly, monthly, quarterly and yearly steps also get a `period` label such as `2026-W03`, `2026-01` or `2026-Q1`. - `backtestErrorPct` is the headline error of the backtest: WAPE for amounts that add up (sales, orders, visits) or when values are near zero, otherwise MAPE. `improvementVsNaivePct` is how much smaller the error was than repeating the last cycle; below zero means the simple rule did better on that window, which happens with short or erratic histories. - `unusualValues` lists each spike or drop with its date, value, expected value and range, a score and `above` or `below`. - `covariates` names the columns used, and which of them had known future values. - Series that can't be forecast have `"status": "failed"` and an `error` that says why. They are never charged. The run's key-value store also has `forecast.csv` (every step of every series, ready for Excel or Google Sheets), the charts, and `OUTPUT` with the forecasts of up to 300 series as JSON. ### Accuracy Chronos-2 has no knowledge of your business, so a forecast is only as good as the history and covariates it gets. That's why every forecast comes with a backtest. Some results from our tests: - **NOAA's Mauna Loa CO₂ record** (monthly since 1958, 24 months ahead): an average error of 0.1% (MAPE) over three past two-year windows, 86% less error than repeating the previous year, and the 80% interval held 97% of the actual values. - **Simulated daily sales of two stores** with a weekly pattern, promotions, holidays and injected data errors (28 days ahead): an average error of about 6% (WAPE), 41% to 48% less error than repeating the last week. Giving the model the promotion calendar as a covariate cut the error from 11–13% to 6–7% on promotion-heavy series, and the injected spikes and drop were the only values flagged as unusual. These numbers come from simulated data, so treat them as an illustration. - **Short histories** (less than two cycles, such as a year of monthly data) are harder for any method: expect larger errors and wider intervals, and read the backtest. ### Pricing You pay per **series forecast**, at the price shown on this page, with its intervals, backtest, summary and chart included. Series that can't be read or forecast are never charged. If you set a maximum cost per run, the Actor stops before the series that wouldn't fit. ### Speed A forecast through the `run-sync` API endpoint usually answers in 8 to 20 seconds from the request, most of it the run starting up and loading the model; the forecast itself takes about a second. At the default 2 GB of memory, 300 daily series with their backtests took 84 seconds in all. Apify gives one CPU core per 4 GB, so more memory speeds up big batches, while 2 GB of memory is enough for most runs. ### Tips and limits - **Give it enough history**: at least two full cycles of the pattern you care about (two years of monthly data for a yearly pattern, a few weeks of daily data for a weekly one). The model reads up to the last 8,192 steps. - **Future rows**: rows with dates after the last value and the value left empty set the horizon and carry the known future covariates. A covariate without future values still helps the model through its past. - **Amounts or levels**: amounts that add up (sales, orders, visits) are summed when steps are combined, and levels (prices, temperatures, rates) averaged, guessed from the column name. Set `aggregate` when the guess is wrong. - **Dates like 03/04/2025** are read month first unless the data shows otherwise (a 13 or higher in the first place, or dots), and a note says so. ISO dates (`2025-04-03`) are never ambiguous. - **Time zones** are dropped and the local time kept, so hourly data across a daylight saving change stays on its clock. - **Limits**: 500,000 rows or dataset items, files up to 30 MB, 5,000 series per run, 100,000 steps per series (the most recent are kept) and 1,024 forecast steps. - **Datasets**: Apify lets this Actor read only the dataset picked in its **Apify dataset** field. - **Data file links**: CSV, TSV, JSON and Excel files, GitHub file links, Gist links and Google Sheets links (shared as "Anyone with the link" or published to the web). Every site's robots.txt is checked first, and its crawl delay kept. ### For AI agents and developers This Actor works with the [Apify MCP server](https://mcp.apify.com), so AI agents can call it as a tool: send numbers in `values` with a `startDate` (or rows in `data`), and read `summary`, `forecast` and `backtestErrorPct` from the result. A direct API call that waits for the forecast: ```bash curl -X POST "https://api.apify.com/v2/acts/jumblemog~time-series-forecasting/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"values": [820, 932, 901, 934, 1290, 1330, 1320, 1150, 1210, 1300, 1450, 1580], "startDate": "2025-09-01", "frequency": "week", "horizon": 6, "seriesName": "Weekly sign-ups", "chart": false}' ``` `run-sync` instead returns the run's `OUTPUT`: the status, the number of series forecast, a link to `forecast.csv` and each series' summary, forecast, backtest and chart link as JSON. In Python, with the `apify-client` package: ```python from apify_client import ApifyClient client = ApifyClient("YOUR_TOKEN") run = client.actor("jumblemog/time-series-forecasting").call(run_input={ "csv": "date,visits\n2025-09-01,1200\n2025-09-02,1350\n...", "horizon": 14, "holidays": "US", }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["series"], item["summary"]) ``` ### Credits - Forecasting model: [Chronos-2](https://github.com/amazon-science/chronos-forecasting) by Amazon (Apache-2.0), run with [PyTorch](https://pytorch.org) (BSD-3-Clause) and Hugging Face [Transformers](https://github.com/huggingface/transformers) (Apache-2.0). - Data handling: [pandas](https://pandas.pydata.org) and [NumPy](https://numpy.org) (BSD-3-Clause), [holidays](https://github.com/vacanza/holidays) (MIT) and [openpyxl](https://openpyxl.readthedocs.io) (MIT). - Charts: [Vega-Lite](https://vega.github.io/vega-lite/) (BSD-3-Clause) through [vl-convert](https://github.com/vega/vl-convert) (BSD-3-Clause), with the Inter font (SIL Open Font License). - Example data: the Mauna Loa monthly CO₂ record of NOAA's Global Monitoring Laboratory, as packaged by [datasets/co2-ppm](https://github.com/datasets/co2-ppm) (ODC Public Domain Dedication and License). The store sales in the picture are simulated. # Actor input Schema ## `data` (type: `array`): Rows with a date column and one or more number columns, such as \[{"date": "2025-01", "sales": 1200}, ...]. Long data (one row per date and product, store or ticker) and wide data (one column per series) both work, and so do an object of dates and values ({"2025-01": 1200, ...}). To use what you already know about the future (planned promotions, prices), add rows for future dates with the value left empty and the covariate columns filled in. The example is 5 years of monthly CO2 at Mauna Loa (NOAA, public domain). ## `values` (type: `array`): A single series as numbers, oldest first: \[112, 118, 132, 129, ...]. Add Dates, or a Start date (and Frequency), for dated forecasts; otherwise the forecast counts steps. ## `dates` (type: `array`): One date per value, such as \["2025-01-01", "2025-01-02", ...]. Optional. ## `startDate` (type: `string`): The date of the first value when the values have no dates: 2025-01-01 (daily), 2025-01 (monthly), 2025-Q1 (quarterly) or 2025 (yearly). Also used for tables without a date column. ## `series` (type: `array`): Named series, each with its own values and dates or start date: \[{"name": "Store A", "values": \[...], "startDate": "2025-01-01", "frequency": "day"}, ...]. A series can carry covariates, such as "covariates": {"promo": \[0, 1, 0, ...]}; a covariate list longer than the values gives its known future values. ## `csv` (type: `string`): CSV or TSV text with a header row, such as date,sales on the first line and 2025-01-01,1200 on the next. Comma, semicolon, tab and pipe separators work; lines starting with # are skipped. ## `dataUrl` (type: `string`): A link to a CSV, TSV, JSON or Excel (.xlsx) file. Google Sheets share links (shared as "Anyone with the link"), GitHub file links and JSON API answers work. The site's robots.txt is respected. ## `datasetId` (type: `string`): Forecast the items of a dataset in your account, such as a scraper's results with dates and numbers (prices, reviews per day, followers, search interest). Lists of dated items inside each item (timelines, price histories) are read too. Up to 500,000 items; the tool gets read access to this dataset only. ## `dateField` (type: `string`): The column with dates or times. Empty: a column named like date, time, month or timestamp, or year and month columns together. ## `valueFields` (type: `array`): The number columns to forecast, each one a series. Empty: the number columns that aren't ids, years or coordinates (for stock prices, the close). ## `seriesFields` (type: `array`): Columns that tell the series apart in long data, such as store and product, or ticker. Empty: found when dates repeat. ## `covariateFields` (type: `array`): Columns that help predict the values, such as price, promotion or temperature (numbers or labels). Their values in future rows (rows with the value left empty) are used as known future values. ## `frequency` (type: `string`): The time step of the series and the forecast. Auto finds it from the dates; irregular dates (orders, posts) are put on a daily, weekly or monthly grid. Choosing a coarser step than the data's (week for daily data) adds the values up or averages them per step. ## `aggregate` (type: `string`): How to combine several values that fall in the same step, such as many orders on one day. Count rows forecasts the number of rows per step, for data with dates but no number to forecast. ## `fillMissing` (type: `string`): What steps without data mean. Chronos-2 handles gaps itself, so leaving them is usually best; days without orders are 0. ## `horizon` (type: `integer`): How many steps ahead to forecast (12 for a year of months). Empty: the future rows the data lists, or 48 hours, 30 days, 22 business days, 13 weeks, 12 months, 8 quarters or 5 years. ## `intervals` (type: `array`): The ranges the actual values should fall in with these probabilities, such as \[80, 95]: each step gets lower80 and upper80, lower95 and upper95. ## `quantiles` (type: `array`): Quantiles to add to each step, between 0 and 1, such as \[0.05, 0.9] for q5 and q90 (a 90% service level for stock planning). ## `holidays` (type: `string`): A country code (US, GB, DE, FR, IN...) or region (US-CA, GB-SCT, DE-BY) whose public holidays the model should know about, past and future. For daily, business-day, weekly and hourly data. ## `nonNegative` (type: `string`): Keeps forecasts and intervals at 0 or above, for sales, counts and prices. ## `crossLearning` (type: `boolean`): Lets the model use all series of the run together. Helps short series of related items (products of one store); leave off for unrelated series. ## `contextLength` (type: `integer`): The most recent steps of history the model reads. Empty: up to 8,192, the model's limit. ## `seriesName` (type: `string`): A name for the series given in Values. Default: value. ## `backtest` (type: `boolean`): Forecasts the most recent past from the data before it and measures the error (MAE, MAPE, WAPE, MASE), compares it with simply repeating the last cycle, and checks how often the intervals held the actual values. ## `backtestWindows` (type: `integer`): How many past windows to test, each as long as the forecast. Empty: 3, or 1 for runs with more than 100 series. ## `detectAnomalies` (type: `boolean`): Checks the last 512 steps of history for values far outside what the model expected from the values before them (spikes, drops, data errors) and lists them with their expected range. ## `chart` (type: `boolean`): Draws each forecast: the history, the forecast and its intervals, and unusual values. ## `chartFormats` (type: `array`): PNG for chats, emails, docs and slides; SVG and PDF stay sharp at any size; HTML shows each value on hover. ## `chartTheme` (type: `string`): Light or dark background. ## `chartHistory` (type: `integer`): How many past steps the chart shows. Empty: four times the forecast length (at least 60). ## `title` (type: `string`): Title of the first chart. Empty: the series name. ## `maxCharts` (type: `integer`): Charts are drawn for this many series; the rest get forecasts without charts. ## `maxSeries` (type: `integer`): Forecast at most this many series. Each series forecast is one charge. ## Actor input object example ```json { "data": [ { "month": "2021-09", "co2_ppm": 413.26 }, { "month": "2021-10", "co2_ppm": 413.9 }, { "month": "2021-11", "co2_ppm": 414.97 }, { "month": "2021-12", "co2_ppm": 416.67 }, { "month": "2022-01", "co2_ppm": 418.13 }, { "month": "2022-02", "co2_ppm": 419.24 }, { "month": "2022-03", "co2_ppm": 418.76 }, { "month": "2022-04", "co2_ppm": 420.19 }, { "month": "2022-05", "co2_ppm": 420.97 }, { "month": "2022-06", "co2_ppm": 420.94 }, { "month": "2022-07", "co2_ppm": 418.85 }, { "month": "2022-08", "co2_ppm": 417.15 }, { "month": "2022-09", "co2_ppm": 415.91 }, { "month": "2022-10", "co2_ppm": 415.74 }, { "month": "2022-11", "co2_ppm": 417.47 }, { "month": "2022-12", "co2_ppm": 418.99 }, { "month": "2023-01", "co2_ppm": 419.48 }, { "month": "2023-02", "co2_ppm": 420.31 }, { "month": "2023-03", "co2_ppm": 420.99 }, { "month": "2023-04", "co2_ppm": 423.35 }, { "month": "2023-05", "co2_ppm": 424 }, { "month": "2023-06", "co2_ppm": 423.68 }, { "month": "2023-07", "co2_ppm": 421.83 }, { "month": "2023-08", "co2_ppm": 419.68 }, { "month": "2023-09", "co2_ppm": 418.5 }, { "month": "2023-10", "co2_ppm": 418.82 }, { "month": "2023-11", "co2_ppm": 420.46 }, { "month": "2023-12", "co2_ppm": 421.86 }, { "month": "2024-01", "co2_ppm": 422.8 }, { "month": "2024-02", "co2_ppm": 424.55 }, { "month": "2024-03", "co2_ppm": 425.38 }, { "month": "2024-04", "co2_ppm": 426.51 }, { "month": "2024-05", "co2_ppm": 426.9 }, { "month": "2024-06", "co2_ppm": 426.91 }, { "month": "2024-07", "co2_ppm": 425.55 }, { "month": "2024-08", "co2_ppm": 422.99 }, { "month": "2024-09", "co2_ppm": 422.03 }, { "month": "2024-10", "co2_ppm": 422.38 }, { "month": "2024-11", "co2_ppm": 423.85 }, { "month": "2024-12", "co2_ppm": 425.4 }, { "month": "2025-01", "co2_ppm": 426.65 }, { "month": "2025-02", "co2_ppm": 427.09 }, { "month": "2025-03", "co2_ppm": 428.15 }, { "month": "2025-04", "co2_ppm": 429.64 }, { "month": "2025-05", "co2_ppm": 430.51 }, { "month": "2025-06", "co2_ppm": 429.61 }, { "month": "2025-07", "co2_ppm": 427.87 }, { "month": "2025-08", "co2_ppm": 425.48 }, { "month": "2025-09", "co2_ppm": 424.37 }, { "month": "2025-10", "co2_ppm": 424.87 }, { "month": "2025-11", "co2_ppm": 426.46 }, { "month": "2025-12", "co2_ppm": 427.49 }, { "month": "2026-01", "co2_ppm": 428.62 }, { "month": "2026-02", "co2_ppm": 429.35 }, { "month": "2026-03", "co2_ppm": 430.15 }, { "month": "2026-04", "co2_ppm": 431.12 }, { "month": "2026-05", "co2_ppm": 432.34 }, { "month": "2026-06", "co2_ppm": 431.43 }, { "month": "2026-07", "co2_ppm": 429.13 }, { "month": "2026-08", "co2_ppm": 427.55 } ], "frequency": "auto", "aggregate": "auto", "fillMissing": "auto", "intervals": [ 80, 95 ], "nonNegative": "auto", "crossLearning": false, "backtest": true, "detectAnomalies": false, "chart": true, "chartFormats": [ "png" ], "chartTheme": "light", "maxCharts": 25, "maxSeries": 1000 } ``` # Actor output Schema ## `results` (type: `string`): One item per series: summary, forecast steps with intervals, backtest, seasonal pattern, chart link, or the error. ## `table` (type: `string`): One row per series and step. ## `output` (type: `string`): The OUTPUT record: every series' summary, forecast, backtest and chart link in one JSON object. ## `csv` (type: `string`): forecast.csv: one row per series and step. ## `files` (type: `string`): The charts (PNG, SVG, PDF, HTML), forecast.csv and OUTPUT in the run's key-value store. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "data": [ { "month": "2021-09", "co2_ppm": 413.26 }, { "month": "2021-10", "co2_ppm": 413.9 }, { "month": "2021-11", "co2_ppm": 414.97 }, { "month": "2021-12", "co2_ppm": 416.67 }, { "month": "2022-01", "co2_ppm": 418.13 }, { "month": "2022-02", "co2_ppm": 419.24 }, { "month": "2022-03", "co2_ppm": 418.76 }, { "month": "2022-04", "co2_ppm": 420.19 }, { "month": "2022-05", "co2_ppm": 420.97 }, { "month": "2022-06", "co2_ppm": 420.94 }, { "month": "2022-07", "co2_ppm": 418.85 }, { "month": "2022-08", "co2_ppm": 417.15 }, { "month": "2022-09", "co2_ppm": 415.91 }, { "month": "2022-10", "co2_ppm": 415.74 }, { "month": "2022-11", "co2_ppm": 417.47 }, { "month": "2022-12", "co2_ppm": 418.99 }, { "month": "2023-01", "co2_ppm": 419.48 }, { "month": "2023-02", "co2_ppm": 420.31 }, { "month": "2023-03", "co2_ppm": 420.99 }, { "month": "2023-04", "co2_ppm": 423.35 }, { "month": "2023-05", "co2_ppm": 424 }, { "month": "2023-06", "co2_ppm": 423.68 }, { "month": "2023-07", "co2_ppm": 421.83 }, { "month": "2023-08", "co2_ppm": 419.68 }, { "month": "2023-09", "co2_ppm": 418.5 }, { "month": "2023-10", "co2_ppm": 418.82 }, { "month": "2023-11", "co2_ppm": 420.46 }, { "month": "2023-12", "co2_ppm": 421.86 }, { "month": "2024-01", "co2_ppm": 422.8 }, { "month": "2024-02", "co2_ppm": 424.55 }, { "month": "2024-03", "co2_ppm": 425.38 }, { "month": "2024-04", "co2_ppm": 426.51 }, { "month": "2024-05", "co2_ppm": 426.9 }, { "month": "2024-06", "co2_ppm": 426.91 }, { "month": "2024-07", "co2_ppm": 425.55 }, { "month": "2024-08", "co2_ppm": 422.99 }, { "month": "2024-09", "co2_ppm": 422.03 }, { "month": "2024-10", "co2_ppm": 422.38 }, { "month": "2024-11", "co2_ppm": 423.85 }, { "month": "2024-12", "co2_ppm": 425.4 }, { "month": "2025-01", "co2_ppm": 426.65 }, { "month": "2025-02", "co2_ppm": 427.09 }, { "month": "2025-03", "co2_ppm": 428.15 }, { "month": "2025-04", "co2_ppm": 429.64 }, { "month": "2025-05", "co2_ppm": 430.51 }, { "month": "2025-06", "co2_ppm": 429.61 }, { "month": "2025-07", "co2_ppm": 427.87 }, { "month": "2025-08", "co2_ppm": 425.48 }, { "month": "2025-09", "co2_ppm": 424.37 }, { "month": "2025-10", "co2_ppm": 424.87 }, { "month": "2025-11", "co2_ppm": 426.46 }, { "month": "2025-12", "co2_ppm": 427.49 }, { "month": "2026-01", "co2_ppm": 428.62 }, { "month": "2026-02", "co2_ppm": 429.35 }, { "month": "2026-03", "co2_ppm": 430.15 }, { "month": "2026-04", "co2_ppm": 431.12 }, { "month": "2026-05", "co2_ppm": 432.34 }, { "month": "2026-06", "co2_ppm": 431.43 }, { "month": "2026-07", "co2_ppm": 429.13 }, { "month": "2026-08", "co2_ppm": 427.55 } ] }; // Run the Actor and wait for it to finish const run = await client.actor("jumblemog/time-series-forecasting").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "data": [ { "month": "2021-09", "co2_ppm": 413.26, }, { "month": "2021-10", "co2_ppm": 413.9, }, { "month": "2021-11", "co2_ppm": 414.97, }, { "month": "2021-12", "co2_ppm": 416.67, }, { "month": "2022-01", "co2_ppm": 418.13, }, { "month": "2022-02", "co2_ppm": 419.24, }, { "month": "2022-03", "co2_ppm": 418.76, }, { "month": "2022-04", "co2_ppm": 420.19, }, { "month": "2022-05", "co2_ppm": 420.97, }, { "month": "2022-06", "co2_ppm": 420.94, }, { "month": "2022-07", "co2_ppm": 418.85, }, { "month": "2022-08", "co2_ppm": 417.15, }, { "month": "2022-09", "co2_ppm": 415.91, }, { "month": "2022-10", "co2_ppm": 415.74, }, { "month": "2022-11", "co2_ppm": 417.47, }, { "month": "2022-12", "co2_ppm": 418.99, }, { "month": "2023-01", "co2_ppm": 419.48, }, { "month": "2023-02", "co2_ppm": 420.31, }, { "month": "2023-03", "co2_ppm": 420.99, }, { "month": "2023-04", "co2_ppm": 423.35, }, { "month": "2023-05", "co2_ppm": 424, }, { "month": "2023-06", "co2_ppm": 423.68, }, { "month": "2023-07", "co2_ppm": 421.83, }, { "month": "2023-08", "co2_ppm": 419.68, }, { "month": "2023-09", "co2_ppm": 418.5, }, { "month": "2023-10", "co2_ppm": 418.82, }, { "month": "2023-11", "co2_ppm": 420.46, }, { "month": "2023-12", "co2_ppm": 421.86, }, { "month": "2024-01", "co2_ppm": 422.8, }, { "month": "2024-02", "co2_ppm": 424.55, }, { "month": "2024-03", "co2_ppm": 425.38, }, { "month": "2024-04", "co2_ppm": 426.51, }, { "month": "2024-05", "co2_ppm": 426.9, }, { "month": "2024-06", "co2_ppm": 426.91, }, { "month": "2024-07", "co2_ppm": 425.55, }, { "month": "2024-08", "co2_ppm": 422.99, }, { "month": "2024-09", "co2_ppm": 422.03, }, { "month": "2024-10", "co2_ppm": 422.38, }, { "month": "2024-11", "co2_ppm": 423.85, }, { "month": "2024-12", "co2_ppm": 425.4, }, { "month": "2025-01", "co2_ppm": 426.65, }, { "month": "2025-02", "co2_ppm": 427.09, }, { "month": "2025-03", "co2_ppm": 428.15, }, { "month": "2025-04", "co2_ppm": 429.64, }, { "month": "2025-05", "co2_ppm": 430.51, }, { "month": "2025-06", "co2_ppm": 429.61, }, { "month": "2025-07", "co2_ppm": 427.87, }, { "month": "2025-08", "co2_ppm": 425.48, }, { "month": "2025-09", "co2_ppm": 424.37, }, { "month": "2025-10", "co2_ppm": 424.87, }, { "month": "2025-11", "co2_ppm": 426.46, }, { "month": "2025-12", "co2_ppm": 427.49, }, { "month": "2026-01", "co2_ppm": 428.62, }, { "month": "2026-02", "co2_ppm": 429.35, }, { "month": "2026-03", "co2_ppm": 430.15, }, { "month": "2026-04", "co2_ppm": 431.12, }, { "month": "2026-05", "co2_ppm": 432.34, }, { "month": "2026-06", "co2_ppm": 431.43, }, { "month": "2026-07", "co2_ppm": 429.13, }, { "month": "2026-08", "co2_ppm": 427.55, }, ] } # Run the Actor and wait for it to finish run = client.actor("jumblemog/time-series-forecasting").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "data": [ { "month": "2021-09", "co2_ppm": 413.26 }, { "month": "2021-10", "co2_ppm": 413.9 }, { "month": "2021-11", "co2_ppm": 414.97 }, { "month": "2021-12", "co2_ppm": 416.67 }, { "month": "2022-01", "co2_ppm": 418.13 }, { "month": "2022-02", "co2_ppm": 419.24 }, { "month": "2022-03", "co2_ppm": 418.76 }, { "month": "2022-04", "co2_ppm": 420.19 }, { "month": "2022-05", "co2_ppm": 420.97 }, { "month": "2022-06", "co2_ppm": 420.94 }, { "month": "2022-07", "co2_ppm": 418.85 }, { "month": "2022-08", "co2_ppm": 417.15 }, { "month": "2022-09", "co2_ppm": 415.91 }, { "month": "2022-10", "co2_ppm": 415.74 }, { "month": "2022-11", "co2_ppm": 417.47 }, { "month": "2022-12", "co2_ppm": 418.99 }, { "month": "2023-01", "co2_ppm": 419.48 }, { "month": "2023-02", "co2_ppm": 420.31 }, { "month": "2023-03", "co2_ppm": 420.99 }, { "month": "2023-04", "co2_ppm": 423.35 }, { "month": "2023-05", "co2_ppm": 424 }, { "month": "2023-06", "co2_ppm": 423.68 }, { "month": "2023-07", "co2_ppm": 421.83 }, { "month": "2023-08", "co2_ppm": 419.68 }, { "month": "2023-09", "co2_ppm": 418.5 }, { "month": "2023-10", "co2_ppm": 418.82 }, { "month": "2023-11", "co2_ppm": 420.46 }, { "month": "2023-12", "co2_ppm": 421.86 }, { "month": "2024-01", "co2_ppm": 422.8 }, { "month": "2024-02", "co2_ppm": 424.55 }, { "month": "2024-03", "co2_ppm": 425.38 }, { "month": "2024-04", "co2_ppm": 426.51 }, { "month": "2024-05", "co2_ppm": 426.9 }, { "month": "2024-06", "co2_ppm": 426.91 }, { "month": "2024-07", "co2_ppm": 425.55 }, { "month": "2024-08", "co2_ppm": 422.99 }, { "month": "2024-09", "co2_ppm": 422.03 }, { "month": "2024-10", "co2_ppm": 422.38 }, { "month": "2024-11", "co2_ppm": 423.85 }, { "month": "2024-12", "co2_ppm": 425.4 }, { "month": "2025-01", "co2_ppm": 426.65 }, { "month": "2025-02", "co2_ppm": 427.09 }, { "month": "2025-03", "co2_ppm": 428.15 }, { "month": "2025-04", "co2_ppm": 429.64 }, { "month": "2025-05", "co2_ppm": 430.51 }, { "month": "2025-06", "co2_ppm": 429.61 }, { "month": "2025-07", "co2_ppm": 427.87 }, { "month": "2025-08", "co2_ppm": 425.48 }, { "month": "2025-09", "co2_ppm": 424.37 }, { "month": "2025-10", "co2_ppm": 424.87 }, { "month": "2025-11", "co2_ppm": 426.46 }, { "month": "2025-12", "co2_ppm": 427.49 }, { "month": "2026-01", "co2_ppm": 428.62 }, { "month": "2026-02", "co2_ppm": 429.35 }, { "month": "2026-03", "co2_ppm": 430.15 }, { "month": "2026-04", "co2_ppm": 431.12 }, { "month": "2026-05", "co2_ppm": 432.34 }, { "month": "2026-06", "co2_ppm": 431.43 }, { "month": "2026-07", "co2_ppm": 429.13 }, { "month": "2026-08", "co2_ppm": 427.55 } ] }' | apify call jumblemog/time-series-forecasting --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,jumblemog/time-series-forecasting" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/A5apWNkeIizPfu9cT/builds/cFw7kx8lEjbMwhOu8/openapi.json