> 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/core-concepts/which-api-should-i-use.md). # 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 | Goal | API | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Train or improve a demand forecasting model | [Features API](/api/features/get-features.md) with `beam.analysis_id` | | Get event-driven forecasts without building a model | [Forecasts API](/api/forecasts/overview.md) | | Understand which events are driving demand | [Events API](/api/events/search-events.md) with `beam.analysis_id` | | Augment an existing forecast with event-aware outputs | [Forecasts API](/api/forecasts/overview.md) | | Build a dashboard showing upcoming events | [Events API](/api/events/search-events.md) | | Explain a forecast spike to a stakeholder | [Events API](/api/events/search-events.md) | | Identify which event types drive demand at a location | [Beam API](/api/beam/overview.md) | | Ground an LLM or agent inside your own environment | [Events API](/api/events/search-events.md) synced to a local store (provisioned grounding) | | Give an AI agent on-demand access to verified context | [MCP server](/ai/mcp.md) (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: 1. Run Beam. 2. Pass the resulting `analysis_id` to the Features API. {% hint style="warning" %} The Events API is not a substitute for the Features API in forecasting pipelines. Looping over events, counting them per day, and using that count as a model feature is a common mistake that degrades forecast accuracy. {% endhint %} Related resources: * [Features API Reference](/api/features/get-features.md) * [What is the Features API?](/getting-started/core-concepts/what-is-the-features-api.md) ## 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: * [Forecasts API Reference](/api/forecasts/overview.md) * [Getting started with Forecasts API](/getting-started/guides/forecasts-api-guides/getting-started.md) ## 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: * [Events API Reference](/api/events/search-events.md) ## 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: * [Beam API Reference](/api/beam/overview.md) * [What is Beam?](/getting-started/core-concepts/what-is-beam.md) ## 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: * [MCP server](/ai/mcp.md) * [Grounding with PredictHQ](/ai/grounding-with-predicthq.md) ## 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](/how-to-use-predicthq.md) - the recommended integration paths, by job * [Standard integration pattern](/integrations/integration-guides/standard-integration-pattern.md) - how all four APIs fit together in a production architecture * [API quickstart](/getting-started/api-quickstart.md) - make your first API call * [Glossary](/getting-started/glossary.md) - definitions for all core concepts --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.predicthq.com/getting-started/core-concepts/which-api-should-i-use.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.