# Get an Analysis

## Get an Analysis

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

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Beam API","version":"1.0.0"},"tags":[{"name":"Analyses"}],"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"}},"schemas":{"AnalysisResponse":{"type":"object","properties":{"name":{"description":"Name of the Analysis.","type":"string","minLength":1,"title":"Name"},"location":{"description":"The geographic location configured for this analysis.","$ref":"#/components/schemas/LocationResponse"},"rank":{"description":"Specifies which rank type was set to use when calculating event impacts and anomaly detection.","$ref":"#/components/schemas/RankResponse"},"user_id":{"description":"Identifier of the user who owns the Analysis.","type":"string","title":"User Id"},"access_type":{"description":"Access level for the Analysis.","$ref":"#/components/schemas/AccessType"},"status":{"description":"Status of the Analysis.","$ref":"#/components/schemas/AnalysisStatus"},"readiness_status":{"description":"The processing status of the analysis (e.g. `pending`, `ready`, `failed`, `stale`).","$ref":"#/components/schemas/AnalysisReadinessStatus"},"readiness_checks":{"description":"Detailed validation check results from the analysis processing.","$ref":"#/components/schemas/AnalysisReadinessChecks"},"processing_completed":{"description":"Status of the Analysis processing stages. All stages will be present here and are reset to `false` whenever the\nAnalysis is refreshed (i.e., processing has been initiated) then set to `true` when that stage of the\nprocessing is\ncompleted.","$ref":"#/components/schemas/AnalysisProcessingCompleted"},"demand_type":{"description":"The demand type configuration for this analysis.","$ref":"#/components/schemas/DemandTypeResponse"},"group_ids":{"description":"IDs of the groups this Analysis belongs to.","type":"array","items":{"type":"string"},"title":"Group Ids"},"tz":{"description":"The time zone of the Analysis in [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)\nformat.\n\n**Note**: this field is populated automatically based on the location of the Analysis.","type":"string","title":"Tz"},"create_dt":{"description":"Date and time when the Analysis was created (ISO 8601).","type":"string","format":"date-time","title":"Create Dt"},"update_dt":{"description":"Date and time when the Analysis was last updated (ISO 8601).","type":"string","format":"date-time","title":"Update Dt"},"processed_dt":{"description":"Date and time when the Analysis processing completed (ISO 8601).","type":"string","format":"date-time","title":"Processed Dt"},"external_id":{"description":"External identifier associated with the Analysis (optional, user-defined).","type":"string","title":"External Id"},"label":{"description":"Comma-separated list of labels that can be used to search and filter analyses.","type":"array","items":{"type":"string"},"explode":false,"style":"form","title":"Label"},"saved_location":{"description":"Saved Location object at the time of processing the Analysis.","$ref":"#/components/schemas/SavedLocationResponse"}},"required":["name"],"title":"AnalysisResponse"},"LocationResponse":{"description":"Location of the Analysis.\n\nSupports one of the following location options:\n  - `saved_location_id`\n  - `geopoint` with `radius` and `unit`","type":"object","properties":{"geopoint":{"description":"The latitude and longitude coordinates of the analysis location.","$ref":"#/components/schemas/GeoPointResponse"},"radius":{"description":"Must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around\nyour `geopoint` to use for time series modelling and correlation. We **strongly recommend** using the\n[Suggested Radius API](https://docs.predicthq.com/api/suggested-radius/get-suggested-radius) to find a\nsuitable radius for your location/industry.","type":"number","minimum":0,"title":"Radius"},"unit":{"description":"The unit for `radius` where\n  - `m` is meters\n  - `km` is kilometers\n  - `ft` is feet\n  - `mi` is miles","type":"string","enum":["m","mi","km","ft"],"title":"Unit"},"saved_location_id":{"description":"The ID of a previously created Saved Location for your analysis as documented at\n[Saved Locations API](https://docs.predicthq.com/api/saved-locations/create-a-saved-location)","type":"string","minLength":1,"title":"Saved Location Id"}},"title":"LocationResponse"},"GeoPointResponse":{"type":"object","properties":{"lat":{"description":"Latitude coordinate as a decimal number between -90 and 90.","type":"string","pattern":"^[-+]?([1-8]?\\d(\\.\\d+)?|90(\\.0+)?)$","title":"Lat"},"lon":{"description":"Longitude coordinate as a decimal number between -180 and 180.","type":"string","pattern":"^[-+]?(180(\\.0+)?|((1[0-7]\\d)|([1-9]?\\d))(\\.\\d+)?)$","title":"Lon"}},"required":["lat","lon"],"title":"GeoPointResponse"},"RankResponse":{"type":"object","properties":{"type":{"description":"The rank type in use. `phq` uses PHQ Rank (global attendance-based), `local` uses Local Rank (locality-specific).","$ref":"#/components/schemas/RankTypeResponse"},"levels":{"description":"The rank level thresholds applied to this analysis.","$ref":"#/components/schemas/RankLevelsResponse"}},"required":["type"],"title":"RankResponse"},"RankTypeResponse":{"type":"string","enum":["phq","local"],"title":"RankTypeResponse"},"RankLevelsResponse":{"type":"object","properties":{"phq":{"description":"Rank level thresholds for PHQ Rank filtering.","$ref":"#/components/schemas/RankLevel"},"local":{"description":"Rank level thresholds for Local Rank filtering.","$ref":"#/components/schemas/RankLevel"}},"additionalProperties":false,"title":"RankLevelsResponse"},"RankLevel":{"type":"object","properties":{"min":{"description":"Minimum rank value (0-100).","type":"integer","maximum":100,"minimum":0,"title":"Min"},"max":{"description":"Maximum rank value (0-100).","type":"integer","maximum":100,"minimum":0,"title":"Max"}},"required":["min"],"title":"RankLevel"},"AccessType":{"type":"string","enum":["full","limited"],"title":"AccessType"},"AnalysisStatus":{"type":"string","enum":["active","deleted"],"title":"AnalysisStatus"},"AnalysisReadinessStatus":{"description":"The value of this field determines whether or not the Analysis has successfully completed processing.\n\nWhen you upload data for an Analysis the `readiness_status` will be set to `pending` until processing has\ncompleted.","type":"string","enum":["pending","failed","ready","stale"],"title":"AnalysisReadinessStatus"},"AnalysisReadinessChecks":{"description":"Beam performs a number of validation checks on the data provided. The results of some of those checks are\nstored in this field.\n\nWe don't recommend relying on the values in this field as the structure may change without warning. Instead, refer\nto the `readiness_status` field to determine whether or not the Analysis is ready (i.e. has completed\nprocessing successfully).","type":"object","properties":{"date_range":{"description":"The start and end dates of the uploaded demand data.","$ref":"#/components/schemas/AnalysisDateRange"},"error_code":{"description":"Error code if the readiness check failed.","type":"string","title":"Error Code"},"missing_dates":{"description":"List of dates missing from the uploaded demand data.","type":"array","items":{"type":"string"},"title":"Missing Dates"},"validation_response":{"description":"Detailed validation results from the demand data checks.","type":"object","additionalProperties":true,"title":"Validation Response"},"best_practice":{"description":"Whether the analysis configuration meets all best practice requirements.","type":"boolean","default":false,"title":"Best Practice"},"best_practice_checks":{"description":"Detailed results of individual best practice checks for the analysis configuration.","$ref":"#/components/schemas/BestPracticeChecks"}},"title":"AnalysisReadinessChecks"},"AnalysisDateRange":{"type":"object","properties":{"start":{"description":"Start date of the analysis data range.","type":"string","format":"date","title":"Start"},"end":{"description":"End date of the analysis data range.","type":"string","format":"date","title":"End"}},"required":["start","end"],"title":"AnalysisDateRange"},"BestPracticeChecks":{"type":"object","properties":{"industry":{"description":"Indicates whether the analysis industry meets the best practice requirements.","type":"boolean","default":false,"title":"Industry"},"rank":{"description":"Indicates whether the analysis rank configuration meets the best practice requirements.","type":"boolean","default":false,"title":"Rank"},"radius":{"description":"Indicates whether the analysis location radius meets the best practice requirements.","type":"boolean","default":false,"title":"Radius"}},"title":"BestPracticeChecks"},"AnalysisProcessingCompleted":{"type":"object","properties":{"correlation":{"description":"Indicates whether the correlation processing stage has completed.","type":"boolean","default":false,"title":"Correlation"},"feature_importance":{"description":"Indicates whether the feature importance processing stage has completed.","type":"boolean","default":false,"title":"Feature Importance"},"value_quant":{"description":"Indicates whether the value quantification processing stage has completed.","type":"boolean","default":false,"title":"Value Quant"}},"title":"AnalysisProcessingCompleted"},"DemandTypeResponse":{"description":"Indicates the detected type of the uploaded demand data as well as other user-defined information about\nthe demand data.","type":"object","properties":{"industry":{"description":"The detected or configured industry for the demand data.","$ref":"#/components/schemas/Industry"},"interval":{"description":"The time interval of the demand data.\n\nPossible values: `day`, `week`.","default":"day","$ref":"#/components/schemas/Interval"},"week_start_day":{"description":"Week start day (e.g. `sunday`, `monday`). Only present when `interval` is `week`.","$ref":"#/components/schemas/Weekday"},"unit_descriptor":{"description":"The description of the unit of demand, which specifies the type or measure being quantified (e.g.,\n\"Occupancy Rate\", \"Sales\", \"Number of Transactions\").","type":"string","default":"Sales","title":"Unit Descriptor"},"currency_code":{"description":"The ISO 4217 currency code for the units of demand.","default":"USD","$ref":"#/components/schemas/CurrencyCode"},"unit_currency_multiplier":{"description":"The multiplier used to adjust the unit of demand to its equivalent value in the specified currency.","type":"number","default":1,"title":"Unit Currency Multiplier"}},"title":"DemandTypeResponse"},"Industry":{"description":"The industry of the demand data being analysed by Beam. Choosing the right `industry` is important as this will\ndetermine the type of features used in the Analysis and will impact the accuracy of the results.","type":"string","default":"other","enum":["accommodation","cpg","tourism","marketing","parking","restaurants","retail","transportation","other"],"title":"Industry"},"Interval":{"type":"string","enum":["day","week"],"title":"Interval"},"Weekday":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"],"title":"Weekday"},"CurrencyCode":{"description":"The ISO 4217 standard code representing the currency corresponding to the units of demand.","type":"string","default":"USD","enum":["USD","EUR","GBP","AUD","CAD"],"title":"CurrencyCode"},"SavedLocationResponse":{"description":"Saved Location object at the time of processing the Analysis.","type":"object","properties":{"name":{"description":"The user defined name of the Saved Location set in the create location call.","type":"string","title":"Name"},"formatted_address":{"description":"The address of the location. This can be supplied when creating a location.\nIf it's not supplied it will be populated by a reverse geocode.","type":"string","title":"Formatted Address"},"geojson":{"description":"An object containing the geographic information about the saved location. Represents the geometry in the GeoJSON\nformat.","$ref":"#/components/schemas/GeoJsonResponse"},"h3":{"description":"A list of H3 indices that cover the saved location (if applicable).","type":"array","items":{"type":"string"},"title":"H3"},"place_ids":{"description":"An array of place IDs (from the Places API) for locations that are defined as covering an area (e.g. city, state,\ncountry) rather than a point and radius.","type":"array","items":{"type":"integer"},"title":"Place Ids"},"place_hierarchies":{"description":"A list of place hierarchy strings for the saved location.","type":"array","items":{"type":"string"},"title":"Place Hierarchies"},"places":{"description":"A list of Geonames Places corresponding to the saved location. Usually a single item, but always a list.","type":"array","items":{"$ref":"#/components/schemas/PlaceResponse"},"title":"Places"},"subscription_valid_types":{"description":"The list of subscription types that this location is valid for.\n\nPossible values: `events`, `broadcasts`, `features_api`.\n\nIt is possible to create locations outside of what your subscription has access to; in this case this field \nwill be empty and you will not be able to view events for the location.","type":"array","items":{"$ref":"#/components/schemas/SubscriptionValidType"},"title":"Subscription Valid Types"},"location_id":{"description":"The autogenerated identifier for the saved location.","type":"string","title":"Location Id"}},"required":["location_id"],"title":"SavedLocationResponse"},"GeoJsonResponse":{"type":"object","properties":{"type":{"description":"The GeoJSON object type. Always `Feature` for this schema.","type":"string","title":"Type"},"properties":{"description":"Properties associated with the GeoJSON feature, such as radius and radius unit.","$ref":"#/components/schemas/GeoJsonProperties"},"geometry":{"description":"The geometry object containing the coordinate data.","$ref":"#/components/schemas/GeoJsonGeometry"}},"required":["type","geometry"],"title":"GeoJsonResponse"},"GeoJsonProperties":{"type":"object","properties":{"radius":{"description":"Must be an integer or a float number up to 2 decimal places. It represents the radius of the event search around\nyour `geopoint` to use for time series modelling and correlation. We **strongly recommend** using the\n[Suggested Radius API](https://docs.predicthq.com/api/suggested-radius/get-suggested-radius) to find a\nsuitable radius for your location/industry.","type":"number","exclusiveMinimum":0,"title":"Radius"},"radius_unit":{"description":"The unit of measurement for the `radius` value:\n\n- `m` — meters\n- `km` — kilometers\n- `mi` — miles\n- `ft` — feet","$ref":"#/components/schemas/RadiusUnit"}},"required":["radius","radius_unit"],"title":"GeoJsonProperties"},"RadiusUnit":{"type":"string","enum":["m","km","mi","ft"],"title":"RadiusUnit"},"GeoJsonGeometry":{"type":"object","properties":{"type":{"description":"The GeoJSON geometry type (e.g. `Point`, `Polygon`, `MultiPolygon`, `LineString`, `MultiLineString`).","$ref":"#/components/schemas/GeoJsonGeometryType"},"coordinates":{"description":"The GeoJSON coordinates array whose structure depends on the geometry `type`:\n\n- `Point` — `[lon, lat]`\n- `LineString` — an array of `[lon, lat]` positions\n- `Polygon` — an array of linear rings, each a list of `[lon, lat]` positions\n- `MultiLineString` — an array of `LineString` coordinate arrays\n- `MultiPolygon` — an array of `Polygon` coordinate arrays","type":"array","minItems":1,"title":"Coordinates"}},"required":["type","coordinates"],"title":"GeoJsonGeometry"},"GeoJsonGeometryType":{"type":"string","enum":["Point","Polygon","MultiPolygon","LineString","MultiLineString"],"title":"GeoJsonGeometryType"},"PlaceResponse":{"type":"object","properties":{"place_id":{"description":"The Geonames Place ID.","type":"integer","title":"Place Id"},"type":{"description":"The type of place (e.g. city, state, country).","type":"string","title":"Type"},"name":{"description":"The name of the place.","type":"string","title":"Name"},"county":{"description":"The county the place belongs to, if applicable.","type":"string","title":"County"},"region":{"description":"The region or state the place belongs to, if applicable.","type":"string","title":"Region"},"country":{"description":"The country the place belongs to.","type":"string","title":"Country"},"geojson":{"description":"GeoJSON representation of the place geometry.","$ref":"#/components/schemas/GeoJsonResponse"}},"required":["place_id","type","name","geojson"],"title":"PlaceResponse"},"SubscriptionValidType":{"type":"string","enum":["broadcasts","events","features_api"],"title":"SubscriptionValidType"},"HTTPError":{"type":"object","properties":{"error":{"description":"A human-readable error message.","type":"string","title":"Error"}},"required":["error"],"title":"HTTPError"}}},"paths":{"/v1/beam/analyses/{analysis_id}":{"get":{"operationId":"get_analysis","summary":"Get an Analysis","description":"Returns the full details of a single Analysis, including its location, demand type, rank, readiness status, and processing state.","parameters":[{"name":"analysis_id","in":"path","description":"An existing Beam Analysis ID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}}},"403":{"description":"Bearer token scope insufficient","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}}},"404":{"description":"Analysis not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}}}},"tags":["Analyses"]}}}}
```

## Examples

{% tabs %}
{% tab title="curl" %}

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

{% endtab %}

{% tab title="python" %}

```python
import requests

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

print(response.json())
```

{% endtab %}
{% endtabs %}

## OpenAPI Spec

The OpenAPI spec for Beam API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Beam+API).

## Guides

Below are some guides relevant to this API:

* [Beam Guides](/getting-started/guides/beam-guides.md)


---

# 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/beam/analyses/get-an-analysis.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.