Get an Analysis

Get an existing Analysis.

Request

HTTP Request

GET https://api.predicthq.com/v1/beam/analyses/

Path Parameters

Parameter Description

Parameter	Description
`analysis_id`	An existing Beam Analysis ID.

analysis_id

An existing Beam Analysis ID.

Response

Response Fields

Field Description

Field	Description
`name` string	Name of the Analysis. E.g. `My Location Analysis 1`
`create_dt` string	The creation date time for the Analysis in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`update_dt` string	The last update date time for the Analysis in ISO 8601 format format. E.g. `2022-04-26T11:46:24+00:00`
`processed_dt` string	The date time the Analysis was last processed in ISO 8601 format format. E.g. `2022-04-26T11:46:25+00:00`
`user_id` string	The ID of the user who created the Analysis. This is present for Analyses created in Control Center. For Analyses created via the API this field will not be populated. E.g. `hjqkKozgS8mm`
`access_type` string	Indicates whether or not your subscription has access to the provided location. We allow creating Analyses for any location, even locations outside of your subscription. However, for locations outside of your subscription the `access_type` will be set as `limited` and certain functionality might not be available. Possible values: `full` `limited` E.g. `full`
`location` object	Location of the Analysis. E.g. `{ "location": { "geopoint": { "lat": "-36.849761", "lon": "174.7628903" }, "radius": 1.2, "unit": "km" } }`
`rank` object	Specifies which rank type was set to use when calculating event impacts and anomaly detection. E.g. `{ "rank": { "type": "phq", "levels": { "phq": { "min": 51 } } } }`
`tz` string	The time zone of the Analysis in TZ Database format. E.g. `Pacific/Auckland` Note: this field is being used in the Control Center Beam UI for the purpose of fetching a list of relevant events in the correct time zone. It no longer has bearing on the outcome of a Beam analysis.
`readiness_checks` object	Beam performs a number of validation checks on the data provided. The results of some of those checks are stored in this field. We don't recommend relying on the values in this field as the structure may change without warning. Instead, refer to the `readiness_status` field to determine whether or not the Analysis is ready. E.g. `{ "readiness_checks": { "date_range": { "start": "2017-01-01", "end": "2017-12-31" }, "validation_response": { "missing_data_percentage": 0.0, "consecutive_nan": 0 } } }`
`readiness_status` string	The value of this field determines whether or not the Analysis is ready for correlation. When you upload data for an Analysis the `readiness_status` will be set to `pending` until processing has completed. Possible values: `pending` `failed` `ready` E.g. `ready`
`status` string	Status of the Analysis. Possible values: `draft` `active` E.g. `active`
`processing_completed` object	Status of the analysis processing stages. Only present in newly created or refreshed analyses. E.g. `{ "processing_completed": { "correlation": true, "feature_importance": false } }`

name string

Name of the Analysis. E.g. My Location Analysis 1

create_dt string

The creation date time for the Analysis in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00

update_dt string

The last update date time for the Analysis in ISO 8601 format format.

E.g. 2022-04-26T11:46:24+00:00

processed_dt string

The date time the Analysis was last processed in ISO 8601 format format.

E.g. 2022-04-26T11:46:25+00:00

user_id string

The ID of the user who created the Analysis. This is present for Analyses created in Control Center. For Analyses created via the API this field will not be populated.

E.g. hjqkKozgS8mm

access_type string

Indicates whether or not your subscription has access to the provided location.

We allow creating Analyses for any location, even locations outside of your subscription. However, for locations outside of your subscription the access_type will be set as limited and certain functionality might not be available.

Possible values:

full
limited

E.g. full

location object

Location of the Analysis. E.g.

{
  "location": {
    "geopoint": {
      "lat": "-36.849761",
      "lon": "174.7628903"
    },
    "radius": 1.2,
    "unit": "km"
  }
}

rank object

Specifies which rank type was set to use when calculating event impacts and anomaly detection. E.g.

{
  "rank": {
    "type": "phq",
    "levels": {
      "phq": {
        "min": 51
      }
    }
  }
}

tz string

The time zone of the Analysis in TZ Database format.

E.g. Pacific/Auckland

Note: this field is being used in the Control Center Beam UI for the purpose of fetching a list of relevant events in the correct time zone. It no longer has bearing on the outcome of a Beam analysis.

readiness_checks object

Beam performs a number of validation checks on the data provided. The results of some of those checks are stored in this field.

We don't recommend relying on the values in this field as the structure may change without warning. Instead, refer to the readiness_status field to determine whether or not the Analysis is ready. E.g.

{
  "readiness_checks": {
    "date_range": {
      "start": "2017-01-01",
      "end": "2017-12-31"
    },
    "validation_response": {
      "missing_data_percentage": 0.0,
      "consecutive_nan": 0
    }
  }
}

readiness_status string

The value of this field determines whether or not the Analysis is ready for correlation.

When you upload data for an Analysis the readiness_status will be set to pending until processing has completed. Possible values:

pending
failed
ready

E.g. ready

status string

Status of the Analysis. Possible values:

draft
active

E.g. active

processing_completed object

Status of the analysis processing stages. Only present in newly created or refreshed analyses.

E.g.

{
  "processing_completed": {
    "correlation": true,
    "feature_importance": false
  }
}

Example response

Below is an example response:

{
    "name": "Analysis 1",
    "location": {
        "geopoint": {
            "lat": "-36.849761",
            "lon": "174.7628903"
        },
        "radius": 1.2,
        "unit": "km"
    },
    "rank": {
        "type": "phq",
        "levels": {
            "phq": {
                "min": 51
            }
        }
    },
    "status": "draft",
    "create_dt": "2023-03-01T23:03:19.403859+00:00",
    "update_dt": "2023-03-01T23:49:39.464011+00:00",
    "user_id": null,
    "access_type": "full",
    "processed_dt": "2023-03-01T23:43:52.253150+00:00",
    "readiness_status": "ready",
    "readiness_checks": {
        "date_range": {
            "start": "2017-01-01",
            "end": "2017-12-31"
        },
        "validation_response": {
            "missing_data_percentage": 0.0,
            "consecutive_nan": 0
        }
    },
    "processing_completed": {
        "correlation": true,
        "feature_importance": true
    },
    "tz": "UTC"
}

Examples

curl -X GET https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/beam/analyses/<analysis_id>",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    }
)

print(response.json())

Guides

Below are some guides relevant to this API:

Beam Data Science Guide

PreviousSearch Analyses NextUpdate an Analysis

Last updated 19 days ago