> 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/how-to-use-predicthq.md).

# How to use PredictHQ

PredictHQ is the real-world context platform powering enterprise AI decisions. Its verified events, predicted impacts, and demand-calibrated features are consumed along a recommended path for each job: train your forecasting models on event features, ground LLMs and agents in verified context at answer time, get event-driven forecasts without building a model, or analyze what drives demand at your locations. This page routes you to the right path and shows how the paths fit together.

## Start with the job you're doing

| Your job                                               | Path                                                                                  |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| Improve the accuracy of a forecasting model you own    | [Train your models on event features](#train-your-models-on-event-features)           |
| Get event-driven forecasts without building a model    | [Get forecasts without building a model](#get-forecasts-without-building-a-model)     |
| Stop an LLM or AI agent guessing about the real world  | [Ground your AI in verified context](#ground-your-ai-in-verified-context)             |
| Understand which events drive demand at your locations | [Understand what drives your demand](#understand-what-drives-your-demand)             |
| Show operators the events behind a demand shift        | [Events API](/api/events/search-events.md) with `beam.analysis_id` for explainability |

Whichever path you take, the first two steps are the same, and they calibrate everything downstream:

1. Create a [Saved Location](/api/saved-locations/overview.md) for each business location using `origin_geojson` - Predicted Impact Area is calculated automatically, defining where events actually affect that location.
2. Run [Beam](/getting-started/core-concepts/what-is-beam.md), PredictHQ's relevancy engine, with your historical demand data. The resulting `analysis_id` scopes every downstream call to the event categories and thresholds that drive demand at that location.

## Train your models on event features

For data science teams who own a forecasting model and want it more accurate.

Retrieve model-ready features from the [Features API](/api/features/get-features.md) keyed by your `beam.analysis_id`: historical windows to train on alongside your demand history, and future-dated windows at every forecast run. Because events are known in advance, the future values are real demand signals rather than estimates - no zero-filling the forecast horizon.

Using a pre-trained time series foundation model instead? There is no training step - supply the same future-dated features as covariates. See [Using event features with time series foundation models](/getting-started/guides/features-api-guides/using-event-features-with-time-series-foundation-models.md).

* [Which API should I use?](/getting-started/core-concepts/which-api-should-i-use.md)
* [Standard integration pattern](/integrations/integration-guides/standard-integration-pattern.md) - the production architecture

## Get forecasts without building a model

For teams that want event-driven forecast accuracy with rapid time-to-value, without building or maintaining a forecasting pipeline.

Supply historical demand data to the [Forecasts API](/api/forecasts/overview.md) and it trains a model, applies Beam automatically, and returns daily-level forecasts with event impact and explainability built in. A baseline comparison shows the accuracy improvement attributable to PredictHQ data - measured on your own demand.

The Forecasts API also fits multi-model setups: run it as one candidate in a champion-challenger selection or an ensemble alongside your existing forecasts, and let measured accuracy decide which wins each series. Nothing needs replacing to adopt it.

* [Getting started with Forecasts API](/getting-started/guides/forecasts-api-guides/getting-started.md)

## Ground your AI in verified context

For ML platform and agent teams whose LLMs or agents make demand-related decisions, where an AI hallucination (a confident, plausible, wrong answer) carries real cost.

Grounding gives a model the real-world facts it lacks at the moment it answers, so it responds from what is true instead of hallucinating. Retrieval-augmented generation (RAG) is one technique for achieving it. PredictHQ supports two grounding architectures; most deployments choose one, and which fits is mostly a governance and maintenance question:

* **Internal grounding** - verified event context is delivered into your environment (Snowflake, AWS Data Exchange, SFTP, or API sync) and your AI systems retrieve from a store you govern. Choose this when data residency, governance, or retrieval scale matter.
* **External grounding** - your agents query the [PredictHQ MCP server](/ai/mcp.md) on demand and hold no copy of anything. Choose this when zero pipeline maintenance matters, or when you want to be up and running today without waiting on your platform team's roadmap.
* [Grounding LLMs in real-world event data (RAG)](/ai/grounding-llms-in-real-world-data.md) - concepts, architectures, and FAQ
* [Internal grounding: retrieval inside your environment](/integrations/integration-guides/internal-grounding.md) - the reference architecture
* [PredictHQ MCP in agentic workflows](/ai/predicthq-mcp-in-agentic-workflows.md)

## Understand what drives your demand

For analysts and data scientists who need to know which real-world events matter before committing to a build - or need evidence for what happened.

Beam's [Feature Importance](/api/beam/analyses/get-feature-importance.md) results rank the event categories that drive demand at each location and quantify how much of your demand variability is event-driven. PredictHQ explains more than 60 percent of real-world demand variability. Drill into the specific events behind any shift with the [Events API](/api/events/search-events.md) using the same `analysis_id`.

* [Understanding demand variability and event contribution in Beam](/getting-started/guides/beam-guides/understanding-demand-variability-and-event-contribution-in-beam.md)

## How the paths fit together

Training improves your model before it runs. Grounding supplies verified context while it runs. The two never mix - grounding doesn't touch the training model - and the two grounding architectures are alternatives to each other, not to training. Time series foundation models don't change this split; they shrink the training step and move more of the value to inference time.

The paths share the same foundation, so they combine naturally: the Saved Locations and Beam analyses you set up for a forecasting integration are the same ones that scope a grounding corpus or an agent's MCP queries. Many production deployments run a training path and a grounding path side by side - a model trained on event features, and an AI layer that explains its outputs from verified event context.

## Next steps

* [API quickstart](/getting-started/api-quickstart.md) - make your first call
* [Which API should I use?](/getting-started/core-concepts/which-api-should-i-use.md) - per-task API selection
* [Standard integration pattern](/integrations/integration-guides/standard-integration-pattern.md) - the production reference architecture


---

# 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/how-to-use-predicthq.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.