# Get Forecast {% hint style="info" %} Please note that `phq_features` can only be retrieved if you have also purchased the Features product. {% endhint %} ## Get Forecast > Returns the generated forecast results for a trained model. Each result includes a date and predicted demand value. Supports filtering by date range. ```json {"openapi":"3.1.0","info":{"title":"PredictHQ Forecasts API (Public Preview)","version":"1.0.0"},"tags":[{"name":"Forecasts"}],"servers":[{"url":"https://api.predicthq.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"$API_KEY","description":"Enter your PredictHQ API key. The Bearer prefix is added automatically.\n\nWhen calling the API directly, send: `Authorization: Bearer ` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"parameters":{"LimitParam":{"name":"limit","in":"query","description":"The maximum number of results to return per page. Defaults to `10`.","required":false,"schema":{"type":"integer","default":10}},"OffsetParam":{"name":"offset","in":"query","description":"The number of results to skip before returning. Used for pagination. Defaults to `0`.","required":false,"schema":{"type":"integer","default":0}}},"schemas":{"SearchModelForecastResponse":{"type":"object","properties":{"errors":{"description":"List of error messages, if any.","type":"array","items":{"type":"string"},"default":[],"title":"Errors"},"warnings":{"description":"List of warning messages, if any.","type":"array","items":{"type":"string"},"default":[],"title":"Warnings"},"count":{"description":"Total number of results matching the query.","type":"integer","title":"Count"},"next":{"description":"URL for the next page of results. Null if no more results.","anyOf":[{"type":"string"},{"type":"null"}],"title":"Next"},"previous":{"description":"URL for the previous page of results. Null if on the first page.","anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous"},"results":{"description":"Array of forecast results for the current page.","type":"array","items":{"$ref":"#/components/schemas/PublicForecast"},"title":"Results"}},"required":["count"],"title":"SearchModelForecastResponse"},"PublicForecast":{"type":"object","properties":{"date":{"description":"The date of the forecast value.","type":"string","format":"date","title":"Date"},"forecast":{"description":"The predicted demand value for the date.","type":"number","title":"Forecast"},"phq_explainability":{"description":"Events impacting demand on this date, ranked by impact. Only present when `phq_explainability` is passed in the `include` query parameter.","$ref":"#/components/schemas/PhqExplainability"},"phq_features":{"description":"List of the features (from our Features API) that were shown to have an impact on the demand. These features were used in training the model and for forecasting.","type":"array","items":{"$ref":"#/components/schemas/Feature"},"minItems":1,"title":"Phq Features"}},"required":["date","forecast"],"title":"PublicForecast"},"PhqExplainability":{"description":"List of the top events impacting demand on each date. Use this to help understand the context of how and why events are impacting your demand.","type":"object","properties":{"events":{"description":"List of events impacting demand on the associated date, ordered by impact.","type":"array","items":{"$ref":"#/components/schemas/Event"},"minItems":0}}},"Event":{"type":"object","properties":{"id":{"description":"Unique identifier of the event.","type":"string","minLength":1,"title":"Id"},"category":{"description":"Category classification of the event (e.g. `conferences`, `sports`, `concerts`).","type":"string","minLength":1,"title":"Category"},"title":{"description":"Display name of the event as it appears in the PredictHQ event catalog.","type":"string","minLength":1,"title":"Title"},"start_local":{"description":"Start date and time of the event in local time.","type":"string","format":"date-time","title":"Start"},"end_local":{"description":"End date and time of the event in local time.","type":"string","format":"date-time","title":"End"},"phq_rank":{"description":"PHQ Rank score from 0–100 indicating the predicted attendance impact of the event.","type":"integer","maximum":100,"minimum":0,"title":"PHQ Rank"},"local_rank":{"description":"Local Rank score from 0–100 indicating relative local significance. Null for non-attended events.","anyOf":[{"type":"integer","maximum":100,"minimum":0},{"type":"null"}],"title":"Local Rank"}},"required":["id","title","category","start_local","end_local"],"title":"Event"},"Feature":{"type":"object","properties":{"name":{"description":"Name of the demand intelligence feature.","type":"string","minLength":1,"title":"Name"},"value":{"description":"Numeric value of the feature's contribution to the forecast.","type":"number","title":"Value"}},"required":["name","value"],"title":"Feature"},"ErrorResponse":{"type":"object","properties":{"error":{"description":"Error message","type":"string","title":"Error"}},"required":["error"],"title":"ErrorResponse"},"HTTPValidationError":{"type":"object","properties":{"error":{"description":"Error summary message","type":"string","title":"Error"},"details":{"description":"List of validation error details","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Details"}},"required":["error","details"],"title":"HTTPValidationError"},"ValidationErrorDetail":{"type":"object","properties":{"field":{"description":"The field that failed validation","type":"string","title":"Field"},"msg":{"description":"The validation error message","type":"string","title":"Message"},"type":{"description":"The type of validation error","type":"string","title":"Error Type"}},"required":["field","msg","type"],"title":"ValidationErrorDetail"},"QueryValidationError":{"type":"object","properties":{"error":{"description":"List of query parameter validation errors","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Error"}},"required":["error"],"title":"QueryValidationError"}}},"paths":{"/v1/forecasts/models/{model_id}/forecast":{"get":{"operationId":"get_forecast","summary":"Get Forecast","description":"Returns the generated forecast results for a trained model. Each result includes a date and predicted demand value. Supports filtering by date range.","parameters":[{"name":"model_id","in":"path","description":"The unique identifier of the forecast model.","required":true,"schema":{"type":"string","title":"Model Id"}},{"name":"date.gt","in":"query","description":"Filters forecast results after the specified date (exclusive).\n\n\nExpected format: `YYYY-MM-DD`","required":false,"schema":{"type":"string","format":"date"}},{"name":"date.gte","in":"query","description":"Filters forecast results on or after the specified date.\n\n\nExpected format: `YYYY-MM-DD`.\n\n\nExample: `2025-01-01`","required":false,"schema":{"type":"string","format":"date"}},{"name":"date.lt","in":"query","description":"Filters forecast results before the specified date (exclusive).\n\n\nExpected format: `YYYY-MM-DD`.","required":false,"schema":{"type":"string","format":"date"}},{"name":"date.lte","in":"query","description":"Filters forecast results on or before the specified date.\n\n\nExpected format: `YYYY-MM-DD`.\n\n\nExample: `2025-01-07`","required":false,"schema":{"type":"string","format":"date"}},{"name":"include","in":"query","description":"A comma-separated list of additional fields to include in each forecast result. By default these fields are omitted:\n\n- `phq_features`: The demand intelligence features used in training and forecasting.\n- `phq_explainability`: The top events impacting demand on each forecasted date.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["phq_features","phq_explainability"]},"title":"Include"}},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/OffsetParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchModelForecastResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/HTTPValidationError"},{"$ref":"#/components/schemas/QueryValidationError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Forecasts"]}}}} ``` ## OpenAPI Spec The OpenAPI spec for Forecasts API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Forecasts+API). ## Guides * [Getting Started with Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/getting-started) * [Understanding Forecast Accuracy Metrics](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/understanding-forecast-accuracy-metrics) * [Troubleshooting Guide for Forecasts API](https://docs.predicthq.com/getting-started/guides/forecasts-api-guides/troubleshooting) --- # Agent Instructions: 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: ``` GET https://docs.predicthq.com/api/forecasts/forecasts/get-forecast.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.