# Search Models

## Search Models

> Returns a paginated list of forecast models belonging to the authenticated organization. Supports full-text search across \`name\`, \`label\`, and \`external\_id\` via the \`q\` parameter, and filtering by Saved Location ID and readiness status.

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Forecasts API (Public Preview)","version":"1.0.0"},"tags":[{"name":"Models"}],"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 <YOUR_API_KEY>` 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":{"SearchModelResponse":{"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 model results for the current page.","type":"array","items":{"$ref":"#/components/schemas/PublicForecastModel"},"title":"Results"}},"required":["count"],"title":"SearchModelResponse"},"PublicForecastModel":{"type":"object","properties":{"algo":{"description":"The forecasting algorithm used by this model.","$ref":"#/components/schemas/AlgoType"},"create_dt":{"description":"Timestamp when the model was created.","type":"string","format":"date-time","title":"Create Dt"},"demand_type":{"description":"Configuration for demand data type including industry and interval.","anyOf":[{"$ref":"#/components/schemas/PublicDemandType"},{"type":"null"}]},"external_id":{"description":"User-provided external identifier for cross-referencing with other systems.","anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"External Id"},"forecast_window":{"description":"Number of days into the future this model forecasts.","$ref":"#/components/schemas/ForecastWindowDay"},"label":{"description":"Set of labels for identifying or grouping forecast models.","anyOf":[{"items":{"type":"string","minLength":1},"type":"array","minItems":1},{"type":"null"}],"title":"Label"},"location":{"description":"The geographic area associated with this model, defined by a Saved Location.","$ref":"#/components/schemas/Location"},"metrics":{"description":"Training and accuracy metrics for the model. Null until the model has been trained.","anyOf":[{"$ref":"#/components/schemas/PublicMetrics"},{"type":"null"}]},"model_id":{"description":"Unique identifier for the forecast model.","type":"string","minLength":1,"title":"Model Id"},"name":{"description":"Name of the forecast model.","type":"string","minLength":1,"title":"Name"},"readiness":{"description":"Current readiness status of the model indicating where it is in the training/forecasting lifecycle.","$ref":"#/components/schemas/Readiness"},"train_dt":{"description":"Timestamp when the model was last successfully trained. Null if never trained.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Train Dt"},"update_dt":{"description":"Timestamp when the model was last updated.","type":"string","format":"date-time","title":"Update Dt"}},"required":["algo","create_dt","forecast_window","location","model_id","name","readiness","update_dt"],"title":"PublicForecastModel"},"AlgoType":{"type":"string","const":"phq-xgboost"},"PublicDemandType":{"type":"object","properties":{"interval":{"description":"The time interval for demand data aggregation.","anyOf":[{"$ref":"#/components/schemas/PublicInterval"},{"type":"null"}]},"industry":{"description":"Industry classification determining which Predicted Impact Patterns are applied.","anyOf":[{"$ref":"#/components/schemas/Industry"},{"type":"null"}]}},"title":"PublicDemandType"},"PublicInterval":{"type":"string","const":"day","title":"PublicInterval"},"Industry":{"description":"Choosing the right industry is important as this will determine the type of features used in the training and forecasting and will impact the accuracy of the results. We will use the applicable Predicted Impact Patterns for the specified industry.","type":"string","enum":["accommodation","cpg","tourism","marketing","parking","restaurants","retail","transportation","other"],"title":"Industry"},"ForecastWindowDay":{"type":"string","enum":["1d","7d","14d","28d","30d","60d","90d"],"title":"ForecastWindowDay"},"Location":{"type":"object","properties":{"saved_location_id":{"description":"The unique identifier of a Saved Location defining the geographic area for this model.","type":"string","minLength":1,"title":"Saved Location ID"}},"required":["saved_location_id"],"title":"Location"},"PublicMetrics":{"type":"object","properties":{"accuracy":{"description":"Forecast accuracy metrics. Null until training completes successfully.","anyOf":[{"$ref":"#/components/schemas/Accuracy"},{"type":"null"}]},"demand_data":{"description":"Statistics about the uploaded demand data including the date range covered.","$ref":"#/components/schemas/DemandDataMetrics"},"training_data":{"description":"Training data statistics including date range and missing data information. Null until training completes.","anyOf":[{"$ref":"#/components/schemas/TrainingDataMetrics"},{"type":"null"}]}},"required":["demand_data"],"title":"PublicMetrics"},"Accuracy":{"description":"Forecast accuracy metrics calculated by comparing predicted values against actual historical values. These metrics help assess how well the model is performing.","type":"object","properties":{"mape":{"description":"Mean Absolute Percentage Error (MAPE). Represents the average absolute percentage difference between forecasted and actual values. Lower values indicate more accurate predictions.","type":"number"},"mae":{"description":"Mean Absolute Error (MAE). The average of the absolute differences between forecasted and actual values. Useful for understanding the average magnitude of errors in the forecast.","type":"number"},"rmse":{"description":"Root Mean Squared Error (RMSE). Measures the square root of the average squared differences between forecasted and actual values. It penalizes larger errors more heavily than MAE.","type":"number"},"wape":{"description":"WAPE quantifies the total forecast error as a percentage of the total actual demand. Unlike MAPE, which gives equal weight to each data point, WAPE weights each error by the size of the actual value. This makes it less sensitive to very small actual values, so it's a more reliable measure of accuracy in some situations.","type":"number"}},"required":["mape","mae","rmse","wape"]},"DemandDataMetrics":{"type":"object","properties":{"date_range":{"description":"The date range covered by the uploaded demand data.","$ref":"#/components/schemas/DateRange"}},"required":["date_range"],"title":"DemandDataMetrics"},"DateRange":{"type":"object","properties":{"start":{"description":"Start date of the range.","type":"string","format":"date","title":"Start"},"end":{"description":"End date of the range.","type":"string","format":"date","title":"End"}},"required":["start","end"],"title":"DateRange"},"TrainingDataMetrics":{"type":"object","properties":{"date_range":{"description":"The date range of demand data used for training the model.","$ref":"#/components/schemas/DateRange"},"missing_pct":{"description":"Percentage of dates with missing demand data in the training range (0–100).","type":"number","default":0,"maximum":100,"minimum":0,"title":"Missing Pct"},"missing_dates":{"description":"List of dates with missing demand data. Null if no dates are missing.","anyOf":[{"items":{"type":"string","format":"date"},"type":"array"},{"type":"null"}],"title":"Missing Dates"}},"required":["date_range"],"title":"TrainingDataMetrics"},"Readiness":{"type":"object","properties":{"status":{"description":"Current lifecycle status of the forecast model.","$ref":"#/components/schemas/ReadinessStatus"},"error_code":{"description":"Machine-readable error code when the model is in a failed state.","anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_message":{"description":"Human-readable error description when the model is in a failed state.","anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"required":["status"],"title":"Readiness"},"ReadinessStatus":{"type":"string","enum":["created","failed","forecasting","preparing","ready","stale","training"],"title":"ReadinessStatus"},"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"},"ErrorResponse":{"type":"object","properties":{"error":{"description":"Error message","type":"string","title":"Error"}},"required":["error"],"title":"ErrorResponse"}}},"paths":{"/v1/forecasts/models":{"get":{"operationId":"list_models","summary":"Search Models","description":"Returns a paginated list of forecast models belonging to the authenticated organization. Supports full-text search across `name`, `label`, and `external_id` via the `q` parameter, and filtering by Saved Location ID and readiness status.","parameters":[{"name":"q","in":"query","description":"Fulltext search across `name`, `label` and `external_id`.","required":false,"schema":{"type":"string"}},{"name":"location.saved_location_id","in":"query","description":"A comma-separated list of Saved Location IDs to filter on.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"readiness_status","in":"query","description":"A comma-separated list of forecast model statuses to filter on.\n\n- `created`: Model has been created but not yet trained.\n- `preparing`: Model is locked and gathering data prior to training.\n- `training`: Model is currently being trained on uploaded demand data.\n- `forecasting`: Model is generating forecasts.\n- `ready`: Model has successfully generated forecasts and is available for queries.\n- `stale`: Model configuration or data has changed; retraining is required.\n- `failed`: Processing encountered an error.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["created","failed","forecasting","preparing","ready","stale","training"]}}},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/OffsetParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchModelResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"oneOf":[{"$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"}}}}},"tags":["Models"]}}}}
```

## 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/models/search-models.md?ask=<question>
```

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.