Search Analyses

Search for an existing Analysis.

Search Analyses

get

Returns a paginated list of your Beam Analyses. Supports filtering by status, readiness_status, industry, interval, label, and date range.

Authorizations

AuthorizationstringRequired

Enter your PredictHQ API key. The Bearer prefix is added automatically.

When calling the API directly, send: Authorization: Bearer <YOUR_API_KEY> as documented at https://docs.predicthq.com/api/overview/authenticating

Query parameters

group_idstring[] · max: 100Optional

An Analysis Group ID. Analyses that belong to this group will be returned.

Example: 3ED1zxXqAY

external_idstring[] · max: 100Optional

Comma-separated list of External IDs.

Example: ["id1","id2"]

labelstring[] · max: 100Optional

Comma-separated list of labels.

Example: ["label1","label2","label3"]

location.saved_location_idstring[] · max: 100Optional

Comma-separated list of Saved Location IDs.

Example: ["id1","id2"]

limitintegerOptional

Limit the number of results.

Default: 10

offsetintegerOptional

Offset the results.

Default: 0

updated.gtstring · dateOptional

Return analyses last updated after this date (exclusive).

Example: 2017-01-01

updated.gtestring · dateOptional

Return analyses last updated on or after this date (inclusive).

Example: 2017-01-01

updated.ltstring · dateOptional

Return analyses last updated before this date (exclusive).

Example: 2025-01-07

updated.ltestring · dateOptional

Return analyses last updated on or before this date (inclusive).

Example: 2025-01-07

qstring · max: 500Optional

Filter analyses by name using a text search. Supports partial and prefix matching (e.g., downt will match Downtown Store).

Example: downt

Responses

200

Successful Response

application/json

countintegerRequired

Total number of analyses matching the query.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Bearer token scope insufficient

application/json

get/v1/beam/analyses

GET /v1/beam/analyses HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "analyses": [
    {
      "name": "Analysis 1",
      "create_dt": "2023-03-01T23:03:19.403859+00:00",
      "update_dt": "2023-03-01T23:49:39.464011+00:00",
      "processed_dt": "2023-03-01T23:43:52.253150+00:00",
      "user_id": null,
      "external_id": "id1",
      "label": [
        "label1",
        "label2",
        "label3"
      ],
      "location": {
        "geopoint": {
          "lat": "-36.849761",
          "lon": "174.7628903"
        },
        "radius": 1.2,
        "unit": "km"
      },
      "demand_type": {
        "interval": "week",
        "week_start_day": "monday",
        "industry": "restaurants"
      },
      "rank": {
        "type": "phq",
        "levels": {
          "phq": {
            "min": 51
          }
        }
      },
      "tz": "UTC",
      "readiness_status": "ready",
      "readiness_checks": {
        "date_range": {
          "start": "2017-01-01",
          "end": "2017-12-31"
        },
        "validation_response": {
          "missing_data_percentage": 0,
          "consecutive_nan": 0
        }
      },
      "processing_completed": {
        "correlation": true,
        "feature_importance": true
      },
      "access_type": "full",
      "status": "active"
    }
  ]
}

Examples

curl

curl -X GET "https://api.predicthq.com/v1/beam/analyses?status=draft&sort=updated" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $API_TOKEN"

python

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/beam/analyses",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "status": "draft",
        "sort": "updated"
    }
)

print(response.json())

OpenAPI Spec

The OpenAPI spec for Beam API can be found here.

Guides

Below are some guides relevant to this API:

• Beam Guides