Which API should I use?
PredictHQ has four core APIs, plus the PredictHQ MCP server for AI assistants and agents. Choosing the right one for each task is the most important decision in any integration - using the wrong API is the most common source of unnecessary complexity and poor results.
The short answer
Train or improve a demand forecasting model
Features API with beam.analysis_id
Get event-driven forecasts without building a model
Understand which events are driving demand
Events API with beam.analysis_id
Augment an existing forecast with event-aware outputs
Build a dashboard showing upcoming events
Explain a forecast spike to a stakeholder
Identify which event types drive demand at a location
Ground an LLM or agent inside your own environment
Events API synced to a local store (provisioned grounding)
Give an AI agent on-demand access to verified context
MCP server (on-demand grounding)
Features API - for forecasting and ML
Use the Features API when you are building or improving a demand forecasting model, integrating event signals into an ML pipeline, or generating event-driven inputs for staffing, pricing, or inventory decisions.
The Features API produces pre-engineered, attendance-weighted, duration-adjusted, impact-pattern-aware time-series signals. It encapsulates years of domain expertise in transforming raw event data into reliable demand signals. Do not attempt to replicate this by querying the Events API and aggregating manually - naive aggregation introduces noise and degrades model performance.
Always use beam.analysis_id when calling the Features API. Without it, you must configure feature selection manually - which is error-prone and produces worse results. To use it:
Run Beam.
Pass the resulting
analysis_idto the Features API.
Related resources:
Forecasts API - for ready-to-use event-driven forecasts
Use the Forecasts API when you want accurate, event-driven demand forecasts without building and maintaining your own forecasting model, or when rapid time-to-value is the priority.
The Forecasts API accepts your historical demand data, trains a model, and returns daily-level forecasts with event impact built directly into the output. The Forecasts API applies Beam automatically, so you don't need to configure feature selection manually. The output includes a baseline comparison metric so you can measure the MAPE improvement attributable to PredictHQ data.
The Forecasts API is appropriate whether you are starting from scratch or augmenting an existing forecast. Use it when reducing development time and complexity matters more than owning the underlying model. For teams that require full control over model architecture and feature engineering, the Features API is the recommended alternative.
Related resources:
Events API - for discovery and explainability
Use the Events API when a user or system needs to see specific individual events - for explainability, dashboards, operational context, or event discovery.
The Events API is for understanding what is happening and why demand shifted on a given day. It is the right tool for surfacing event context alongside forecast results, drilling into which events drove a demand spike, or building an interface that lets operators see upcoming events at their locations.
Use the Events API with beam.analysis_id to automatically filter results to the event categories and rank thresholds that are relevant for a given location - the same calibration applied by the Features API.
The Events API is not designed for generating model inputs. Do not loop over events, count them per day, and use those counts as features.
Related resources:
Beam - for demand calibration
Beam is not a data retrieval API - it is PredictHQ's relevancy engine, which tells you which event types drive demand at each of your locations.
Run Beam before building forecasts or configuring the Features API. The analysis_id Beam produces is the key input to both the Features API and Events API, automatically applying the correct location boundary, event category filters, and rank thresholds.
Run Beam once per location and refresh it monthly. It is required for any integration that uses the Features API. For more detail, see:
MCP server - for grounding AI assistants and agents
Use the MCP server when an AI assistant or agent needs verified real-world context on demand - on-demand grounding. It exposes the full API surface through tool calling with the same entitlements as the REST API, and there is no data pipeline to maintain.
To ground AI systems inside your own environment instead (provisioned grounding), sync the Events API into a local store and retrieve from it at answer time - the same store the Standard Integration Pattern uses for explainability.
The MCP server is the grounding path, not the bulk path: for training-scale feature retrieval, use the Features API directly.
Related resources:
Common mistakes
Avoid these common mistakes:
Using the Events API for ML features - The Events API returns individual event records. Aggregating these manually introduces errors in multi-day event handling, lead/lag effects, and rank filtering. Use the Features API instead.
Skipping Beam - Without Beam, you must configure feature selection in the Features API manually. This is error-prone and produces feature sets that are not calibrated to your actual demand patterns.
Calling Features API without
beam.analysis_id- Without a Beam Analysis, you must manually specify location, features, and rank thresholds. This is valid for early exploration but should not be used in production.
See also
Related pages:
How to use PredictHQ - the recommended integration paths, by job
Standard integration pattern - how all four APIs fit together in a production architecture
API quickstart - make your first API call
Glossary - definitions for all core concepts
Last updated
Was this helpful?