---
title: "Get an Analysis"
method: GET
path: "/v1/beam/analyses/{analysis_id}"
tags: ["Analyses"]
---

# Get an Analysis

`GET /v1/beam/analyses/{analysis_id}`

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

## Path parameters

- `analysis_id` string, required

## Response `200`

Successful Response

- AnalysisResponse
  - `name` string, required — Name of the Analysis.
  - `location` LocationResponse — Location of the Analysis. Supports one of the following location options: - `saved_location_id` - `geopoint` with `radius` and `unit`
    - `geopoint` GeoPointResponse
      - `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)
  - `rank` RankResponse
    - `type` 'phq' | 'local', required
    - `levels` RankLevelsResponse
      - `phq` RankLevel
        - `min` integer, required — Minimum rank value (0-100).
        - `max` integer — Maximum rank value (0-100).
      - `local` RankLevel
        - `min` integer, required — Minimum rank value (0-100).
        - `max` integer — Maximum rank value (0-100).
  - `user_id` string — Identifier of the user who owns the Analysis.
  - `access_type` 'full' | 'limited'
  - `status` 'active' | 'deleted'
  - `readiness_status` 'pending' | 'failed' | 'ready' | 'stale' — The value of this field determines whether or not the Analysis has successfully completed processing. When you upload data for an Analysis the `readiness_status` will be set to `pending` until processing has completed.
  - `readiness_checks` AnalysisReadinessChecks — 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 (i.e. has completed processing successfully).
    - `date_range` AnalysisDateRange
      - `start` string, date, required — Start date of the analysis data range.
      - `end` string, date, required — End date of the analysis data range.
    - `error_code` string — Error code if the readiness check failed.
    - `missing_dates` string[] — List of dates missing from the uploaded demand data.
    - `validation_response` object — Detailed validation results from the demand data checks.
    - `best_practice` boolean — Whether the analysis configuration meets all best practice requirements.
    - `best_practice_checks` BestPracticeChecks
      - `industry` boolean — Indicates whether the analysis industry meets the best practice requirements.
      - `rank` boolean — Indicates whether the analysis rank configuration meets the best practice requirements.
      - `radius` boolean — Indicates whether the analysis location radius meets the best practice requirements.
  - `processing_completed` AnalysisProcessingCompleted
    - `correlation` boolean — Indicates whether the correlation processing stage has completed.
    - `feature_importance` boolean — Indicates whether the feature importance processing stage has completed.
    - `value_quant` boolean — Indicates whether the value quantification processing stage has completed.
  - `demand_type` DemandTypeResponse — Indicates the detected type of the uploaded demand data as well as other user-defined information about the demand data.
    - `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.
    - `interval` 'day' | 'week'
    - `week_start_day` 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday'
    - `unit_descriptor` string — The description of the unit of demand, which specifies the type or measure being quantified (e.g., "Occupancy Rate", "Sales", "Number of Transactions").
    - `currency_code` 'USD' | 'EUR' | 'GBP' | 'AUD' | 'CAD' — The ISO 4217 standard code representing the currency corresponding to the units of demand.
    - `unit_currency_multiplier` number — The multiplier used to adjust the unit of demand to its equivalent value in the specified currency.
  - `group_ids` string[] — IDs of the groups this Analysis belongs to.
  - `tz` string — The time zone of the Analysis in [TZ Database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format. **Note**: this field is populated automatically based on the location of the Analysis.
  - `create_dt` string, date-time — Date and time when the Analysis was created (ISO 8601).
  - `update_dt` string, date-time — Date and time when the Analysis was last updated (ISO 8601).
  - `processed_dt` string, date-time — Date and time when the Analysis processing completed (ISO 8601).
  - `external_id` string — External identifier associated with the Analysis (optional, user-defined).
  - `label` string[] — Comma-separated list of labels that can be used to search and filter analyses.
  - `saved_location` SavedLocationResponse — Saved Location object at the time of processing the Analysis.
    - `name` string — The user defined name of the Saved Location set in the create location call.
    - `formatted_address` string — The address of the location. This can be supplied when creating a location. If it's not supplied it will be populated by a reverse geocode.
    - `geojson` GeoJsonResponse
      - `type` string, required — The GeoJSON object type. Always `Feature` for this schema.
      - `properties` GeoJsonProperties
        - `radius` number, required — 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.
        - `radius_unit` 'm' | 'km' | 'mi' | 'ft', required
      - `geometry` GeoJsonGeometry, required
        - `type` 'Point' | 'Polygon' | 'MultiPolygon' | 'LineString' | 'MultiLineString', required
        - `coordinates` unknown[], required — The GeoJSON coordinates array whose structure depends on the geometry `type`: - `Point` — `[lon, lat]` - `LineString` — an array of `[lon, lat]` positions - `Polygon` — an array of linear rings, each a list of `[lon, lat]` positions - `MultiLineString` — an array of `LineString` coordinate arrays - `MultiPolygon` — an array of `Polygon` coordinate arrays
          - unknown
    - `h3` string[] — A list of H3 indices that cover the saved location (if applicable).
    - `place_ids` integer[] — An array of place IDs (from the Places API) for locations that are defined as covering an area (e.g. city, state, country) rather than a point and radius.
    - `place_hierarchies` string[] — A list of place hierarchy strings for the saved location.
    - `places` PlaceResponse[] — A list of Geonames Places corresponding to the saved location. Usually a single item, but always a list.
      - `place_id` integer, required — The Geonames Place ID.
      - `type` string, required — The type of place (e.g. city, state, country).
      - `name` string, required — The name of the place.
      - `county` string — The county the place belongs to, if applicable.
      - `region` string — The region or state the place belongs to, if applicable.
      - `country` string — The country the place belongs to.
      - `geojson` GeoJsonResponse, required
        - `type` string, required — The GeoJSON object type. Always `Feature` for this schema.
        - `properties` GeoJsonProperties
          - `radius` number, required — 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.
          - `radius_unit` 'm' | 'km' | 'mi' | 'ft', required
        - `geometry` GeoJsonGeometry, required
          - `type` 'Point' | 'Polygon' | 'MultiPolygon' | 'LineString' | 'MultiLineString', required
          - `coordinates` unknown[], required — The GeoJSON coordinates array whose structure depends on the geometry `type`: - `Point` — `[lon, lat]` - `LineString` — an array of `[lon, lat]` positions - `Polygon` — an array of linear rings, each a list of `[lon, lat]` positions - `MultiLineString` — an array of `LineString` coordinate arrays - `MultiPolygon` — an array of `Polygon` coordinate arrays
            - unknown
    - `subscription_valid_types` SubscriptionValidType[] — The list of subscription types that this location is valid for. Possible values: `events`, `broadcasts`, `features_api`. It is possible to create locations outside of what your subscription has access to; in this case this field will be empty and you will not be able to view events for the location.
    - `location_id` string, required — The autogenerated identifier for the saved location.
    - `origin_geojson` object — A GeoJSON Feature with a Point geometry representing the exact origin location of the business (as supplied via `origin_geojson` when the Saved Location was created).
      - `type` 'Feature'
      - `geometry` object, required
        - `type` 'Point', required
        - `coordinates` number[], required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Bearer token scope insufficient
- `404` — Analysis not found

---

[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)