---
title: "Search Models"
method: GET
path: "/v1/forecasts/models"
tags: ["Models"]
---

# Search Models

`GET /v1/forecasts/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.

## Query parameters

- `q` string
- `location.saved_location_id` string[]
- `readiness_status` string[]
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- SearchModelResponse
  - `errors` string[] — List of error messages, if any.
  - `warnings` string[] — List of warning messages, if any.
  - `count` integer, required — Total number of results matching the query.
  - `next` string, nullable — URL for the next page of results. Null if no more results.
  - `previous` string, nullable — URL for the previous page of results. Null if on the first page.
  - `results` PublicForecastModel[] — Array of forecast model results for the current page.
    - `algo` 'phq-xgboost', required
    - `create_dt` string, date-time, required — Timestamp when the model was created.
    - `demand_type` PublicDemandType
      - `interval` 'day'
      - `industry` 'accommodation' | 'cpg' | 'tourism' | 'marketing' | 'parking' | 'restaurants' | 'retail' | 'transportation' | 'other' — The industry of the demand data being analysed by Beam. Choosing the right `industry` is important as this will determine the type of features used in the Analysis and will impact the accuracy of the results.
    - `external_id` string, nullable — User-provided external identifier for cross-referencing with other systems.
    - `forecast_window` '1d' | '7d' | '14d' | '28d' | '30d' | '60d' | '90d', required
    - `label` string[], nullable — Set of labels for identifying or grouping forecast models.
    - `location` Location, required — Location of the Analysis. Supports one of the following location options: - `saved_location_id` - `geopoint` with `radius` and `unit`
      - `geopoint` GeoPoint — Contains `lat` and `lon` coordinates for your analysis, e.g. if you are creating an analysis for a store in Seattle you'd specify the latitude and longitude of your store.
        - `lat` string, required — Latitude coordinate as a decimal number between -90 and 90.
        - `lon` string, required — Longitude coordinate as a decimal number between -180 and 180.
      - `radius` number — Must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around your `geopoint` to use for time series modelling and correlation. We **strongly recommend** using the [Suggested Radius API](https://docs.predicthq.com/api/suggested-radius/get-suggested-radius) to find a suitable radius for your location/industry.
      - `unit` 'm' | 'mi' | 'km' | 'ft' — The unit for `radius` where - `m` is meters - `km` is kilometers - `ft` is feet - `mi` is miles
      - `saved_location_id` string — The ID of a previously created Saved Location for your analysis as documented at [Saved Locations API](https://docs.predicthq.com/api/saved-locations/create-a-saved-location)
    - `metrics` PublicMetrics
      - `accuracy` Accuracy — Forecast accuracy metrics calculated by comparing predicted values against actual historical values. These metrics help assess how well the model is performing.
        - `mape` number, required — Mean Absolute Percentage Error (MAPE). Represents the average absolute percentage difference between forecasted and actual values. Lower values indicate more accurate predictions.
        - `mae` number, required — 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.
        - `rmse` number, required — 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.
        - `wape` number, required — 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.
      - `demand_data` DemandDataMetrics, required
        - `date_range` DateRange, required
          - `start` string, date, required — Start date of the range.
          - `end` string, date, required — End date of the range.
      - `training_data` TrainingDataMetrics
        - `date_range` DateRange, required
          - `start` string, date, required — Start date of the range.
          - `end` string, date, required — End date of the range.
        - `missing_pct` number — Percentage of dates with missing demand data in the training range (0–100).
        - `missing_dates` string[], nullable — List of dates with missing demand data. Null if no dates are missing.
    - `model_id` string, required — Unique identifier for the forecast model.
    - `name` string, required — Name of the forecast model.
    - `readiness` Readiness, required
      - `status` 'created' | 'failed' | 'forecasting' | 'preparing' | 'ready' | 'stale' | 'training', required
      - `error_code` string, nullable — Machine-readable error code when the model is in a failed state.
      - `error_message` string, nullable — Human-readable error description when the model is in a failed state.
    - `train_dt` string, date-time, nullable — Timestamp when the model was last successfully trained. Null if never trained.
    - `update_dt` string, date-time, required — Timestamp when the model was last updated.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden

---

[API](https://skmtc.net/predicthq/apis/predicthq-events-api.md) · [All operations](https://skmtc.net/predicthq/apis/predicthq-events-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/predicthq/predicthq-events-api/revisions/66cd8ff349dd/schema)