Get an Analysis

Get an existing Analysis.

Get an Analysis

get

Returns the full details of a single Analysis, including its location, demand type, rank, readiness status, and processing state.

Authorizations

BearerAuth

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

Path parameters

analysis_idstringRequired

An existing Beam Analysis ID.

Responses

200

Successful Response

application/json

namestring · min: 1Required

Name of the Analysis.

Example: Analysis 1

user_idstringOptional

Identifier of the user who owns the Analysis.

access_typestring · enumOptional

Access level for the Analysis.

Example: fullPossible values:

statusstring · enumOptional

Status of the Analysis.

Example: activePossible values:

readiness_statusstring · enumOptional

The processing status of the analysis (e.g. pending, ready, failed, stale).

Example: readyPossible values:

group_idsstring[]Optional

IDs of the groups this Analysis belongs to.

tzstringOptional

The time zone of the Analysis in TZ Database format.

Note: this field is populated automatically based on the location of the Analysis.

Example: Pacific/Auckland

create_dtstring · date-timeOptional

Date and time when the Analysis was created (ISO 8601).

update_dtstring · date-timeOptional

Date and time when the Analysis was last updated (ISO 8601).

processed_dtstring · date-timeOptional

Date and time when the Analysis processing completed (ISO 8601).

external_idstringOptional

External identifier associated with the Analysis (optional, user-defined).

Example: abc123

labelstring[]Optional

Comma-separated list of labels that can be used to search and filter analyses.

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Bearer token scope insufficient

application/json

404

Analysis not found

application/json

get/v1/beam/analyses/{analysis_id}

HTTPcURLJavaScriptPython

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

{
  "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/$ANALYSIS_ID" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $API_TOKEN"

python

OpenAPI Spec

The OpenAPI spec for Beam API can be found here.

Guides

Below are some guides relevant to this API:

• Beam Guides