> For the complete documentation index, see [llms.txt](https://docs.predicthq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models.md).

# Using event features with time series foundation models

Supply PredictHQ event features as future covariates to pre-trained forecasting models such as Chronos-2, TimesFM, and TimeGPT.

Pre-trained forecasting models are applied zero-shot or with light fine-tuning - there is no per-location training step. They learn temporal patterns from large generic corpora, which means real-world drivers such as concerts, sports fixtures, and holidays are invisible to them unless supplied as covariates. Because events are known in advance, PredictHQ features provide real covariate values across the forecast horizon - no zero-filling or lagged proxies.

Most foundation model interfaces accept these as known future covariates - variously called future covariates, exogenous variables, or dynamic features depending on the model. Support varies by model and version: some accept covariates natively, some only through a wrapper framework, and some not at all - so check your model's documentation rather than assuming the covariates are being used.

One difference from a model you train yourself: a trained ML model learned the event-to-demand relationship at training, so inference needs only forward-looking features. A foundation model learns that relationship from its context window, so every forecast run supplies features for both windows - the demand history and the horizon:

```mermaid
sequenceDiagram
    participant Pipe as Your pipeline
    participant Model as Time series foundation model
    participant PHQ as PredictHQ Features API
    Note over Pipe,Model: No training phase - the model arrives pre-trained
    loop Every forecast run
        Pipe->>PHQ: Features for the demand-history window plus the forecast horizon
        PHQ-->>Pipe: Historical + forward-looking features
        Pipe->>Model: Demand history + features, both windows, in context
        Model-->>Pipe: Forecast
    end
```

## Prepare the covariates

1. Run [Beam](/getting-started/core-concepts/what-is-beam.md) for each location to get an `analysis_id`. Foundation model covariate mechanisms are lightweight, and published evaluations show accuracy degrading when they're fed noisy or irrelevant series - Beam limits the covariate set to the event signals that drive demand at that location.
2. Retrieve historical features covering the same period as the demand history you pass to the model:

```json
{
  "beam": { "analysis_id": "$ANALYSIS_ID" },
  "active": { "gte": "$HISTORY_START", "lte": "$NOW" }
}
```

3. Retrieve future features covering the forecast horizon:

```json
{
  "beam": { "analysis_id": "$ANALYSIS_ID" },
  "active": { "gte": "$NOW", "lte": "$FORECAST_END" }
}
```

4. Join both windows to your demand series on date, and pass them through the model's covariates interface alongside the demand history.

## Keep the covariates fresh

Retrieve future features ahead of each forecast run rather than caching them: new events are announced inside the forecast horizon continuously, attendance predictions are revised as events approach, and events are cancelled. Refresh the Beam Analysis monthly by appending new demand data - see the [Standard integration pattern](/integrations/integration-guides/standard-integration-pattern.md) for the production architecture and refresh cadences.

## Related

* [Features API reference](/api/features/get-features.md) - available features and configuration
* [What is the Features API?](/getting-started/core-concepts/what-is-the-features-api.md)
* [Data Leakage in Backtesting](/getting-started/core-concepts/data-leakage-in-backtesting.md) - why forward-looking features don't leak future information into evaluation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.predicthq.com/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.