# Search Analysis Groups

## Search Analysis Groups

> Returns a paginated list of your Analysis Groups. Supports filtering by \`status\`, \`readiness\_status\`,\
> \`industry\`, \`interval\`, and date range.

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Beam API","version":"1.0.0"},"tags":[{"name":"Analysis Groups"}],"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":{"AnalysisGroupStatus":{"description":"Status of the Analysis Group.","type":"string","enum":["active","deleted"],"title":"AnalysisGroupStatus"},"AnalysisGroupReadinessStatus":{"description":"Determines whether the Analysis Group has finished processing.\nWhen the group or its analyses are created, modified, or\nrefreshed, `readiness_status` will be `pending` until processing completes.","type":"string","enum":["pending","failed","ready"],"title":"AnalysisGroupReadinessStatus"},"Interval":{"type":"string","enum":["day","week"],"title":"Interval"},"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"},"AnalysisGroupSortField":{"type":"string","enum":["name","created","updated","-name","-created","-updated"],"title":"AnalysisGroupSortField"},"MultiAnalysisGroupResponse":{"type":"object","properties":{"count":{"description":"Total number of analysis groups matching the query.","type":"integer","title":"Count"},"groups":{"description":"The list of analysis groups in the current page.","type":"array","items":{"$ref":"#/components/schemas/AnalysisGroupResponse"},"title":"Groups"}},"required":["count","groups"],"title":"MultiAnalysisGroupResponse"},"AnalysisGroupResponse":{"type":"object","properties":{"group_id":{"description":"The autogenerated identifier for the analysis group.","type":"string","title":"Group Id"},"name":{"description":"Name of the Analysis Group.","type":"string","minLength":1,"title":"Name"},"analysis_ids":{"description":"Comma-separated list of strings containing the IDs of Analyses included in this Group.","type":"array","items":{"type":"string"},"explode":false,"style":"form","title":"Analysis Ids"},"user_id":{"description":"The ID of the user who created the Analysis Group. Present for groups created in the WebApp; not populated for\ngroups created via the API.","type":"string","title":"User Id"},"processing_completed":{"description":"The value of this field determines whether or not the aggregated Feature Importance is ready to be viewed for an\nAnalysis Group.\nIt also includes an optional list of Analyses which were excluded from processing for various reasons.","$ref":"#/components/schemas/AnalysisGroupProcessingCompleted"},"readiness_status":{"description":"The processing status of the analysis group (e.g. `pending`, `ready`, `failed`).","$ref":"#/components/schemas/AnalysisGroupReadinessStatus"},"demand_type":{"description":"The demand type of the analyses within this group.","$ref":"#/components/schemas/DemandTypeResponse"},"status":{"description":"The current status of the analysis group.","$ref":"#/components/schemas/AnalysisGroupStatus"},"create_dt":{"description":"The creation date time for the Analysis Group in ISO 8601 format.","type":"string","format":"date-time","title":"Create Dt"},"update_dt":{"description":"The last update date time for the Analysis Group in ISO 8601 format.","type":"string","format":"date-time","title":"Update Dt"},"processed_dt":{"description":"Date and time when the Analysis Group processing completed (ISO 8601).","type":"string","format":"date-time","title":"Processed Dt"}},"required":["name"],"title":"AnalysisGroupResponse"},"AnalysisGroupProcessingCompleted":{"description":"Determines whether the aggregated Feature Importance is ready to be viewed for this Analysis Group\nand may include a list of excluded analyses with reasons.","type":"object","properties":{"feature_importance":{"description":"Indicates whether the aggregated Feature Importance is ready to be viewed for this Analysis Group.","type":"boolean","default":false,"title":"Feature Importance"},"value_quant":{"description":"Indicates whether the Value Quant is ready to be viewed for this Analysis Group.","type":"boolean","default":false,"title":"Value Quant"},"excluded_analyses":{"description":"A list of Analyses that were excluded from processing, with reasons.","type":"array","items":{"$ref":"#/components/schemas/ExcludedAnalysis"},"default":[],"title":"Excluded Analyses"}},"title":"AnalysisGroupProcessingCompleted"},"ExcludedAnalysis":{"type":"object","properties":{"analysis_id":{"description":"The ID of the excluded analysis.","type":"string","title":"Analysis Id"},"reason":{"description":"The reason the analysis was excluded from group processing.","$ref":"#/components/schemas/AnalysisExcludedReason"},"excluded_from":{"description":"The processing stages from which this analysis was excluded.","type":"array","items":{"$ref":"#/components/schemas/ExcludedFromReason"},"default":[],"title":"Excluded From"}},"required":["analysis_id","reason"],"title":"ExcludedAnalysis"},"AnalysisExcludedReason":{"type":"string","enum":["analysis_not_found","analysis_deleted","analysis_failed","analysis_not_ready","analysis_demand_type_inconsistent","analysis_feature_importance_incomplete","analysis_value_quant_incomplete"],"title":"AnalysisExcludedReason"},"ExcludedFromReason":{"type":"string","enum":["feature_importance","value_quant"],"title":"ExcludedFromReason"},"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"},"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"},"ValidationError":{"type":"object","properties":{"field":{"description":"The path to the field that failed validation.","type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location"},"msg":{"description":"A human-readable validation error message.","type":"string","title":"Message"},"type":{"description":"The type of validation error.","type":"string","title":"Error Type"}},"required":["field","msg","type"],"title":"ValidationError"},"HTTPError":{"type":"object","properties":{"error":{"description":"A human-readable error message.","type":"string","title":"Error"}},"required":["error"],"title":"HTTPError"}},"parameters":{"OffsetParam":{"name":"offset","in":"query","description":"Offset the results.","required":false,"schema":{"type":"integer","default":0}},"LimitParam":{"name":"limit","in":"query","description":"Limit the number of results.","required":false,"schema":{"type":"integer","default":10}}}},"paths":{"/v1/beam/analysis-groups":{"get":{"operationId":"list_analysis_groups","summary":"Search Analysis Groups","description":"Returns a paginated list of your Analysis Groups. Supports filtering by `status`, `readiness_status`,\n`industry`, `interval`, and date range.","parameters":[{"name":"updated.gt","in":"query","description":"Filters analysis groups updated after the specified date (exclusive).","required":false,"schema":{"type":"string","format":"date"}},{"name":"updated.gte","in":"query","description":"Filters analysis groups updated on or after the specified date.","required":false,"schema":{"type":"string","format":"date"}},{"name":"updated.lt","in":"query","description":"Filters analysis groups updated before the specified date (exclusive).","required":false,"schema":{"type":"string","format":"date"}},{"name":"updated.lte","in":"query","description":"Filters analysis groups updated on or before the specified date.","required":false,"schema":{"type":"string","format":"date"}},{"name":"q","in":"query","description":"Query string to be matched against Group name.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Comma-separated list used to filter analysis groups by their status.\n\n- `active` — returns groups that are currently in use.\n- `deleted` — returns groups that have been deleted.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/AnalysisGroupStatus"}},"explode":false,"style":"form"},{"name":"readiness_status","in":"query","description":"Comma-separated list used to filter analysis groups by their readiness status.\n\n- `pending` — processing in progress.\n- `ready` — processing completed successfully.\n- `failed` — processing failed.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/AnalysisGroupReadinessStatus"}},"explode":false,"style":"form"},{"name":"demand_type.interval","in":"query","description":"Filter analysis groups by their demand data interval.\n\n- `day` — returns groups with daily demand data.\n- `week` — returns groups with weekly demand data.","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Interval"}},"explode":false,"style":"form"},{"name":"demand_type.industry","in":"query","description":"Comma-separated list used to filter analysis groups by industry. Only groups whose analyses match\none of the specified industries are returned.\n\n- `accommodation` — Accommodation providers, travel tech, and OTAs\n- `cpg` — Consumer packaged goods companies\n- `tourism` — Leisure, travel, and tourism businesses (e.g. Expedia, DMOs, travel platforms)\n- `marketing` — Advertising and marketing services\n- `parking` — Parking facility operators\n- `restaurants` — Food and beverage businesses including restaurant groups\n- `retail` — Non-food retail and retail tech\n- `transportation` — On-demand transport and delivery\n- `other` — All other industries","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/Industry"}},"explode":false,"style":"form"},{"name":"sort","in":"query","description":"Comma-separated list used to sort Analysis Groups.\n\nPrefix a value with `-` for descending order.\n\n- `name` / `-name`: A–Z / Z–A\n- `created` / `-created`: oldest first / newest first\n- `updated` / `-updated`: oldest first / newest first","required":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/AnalysisGroupSortField"},"default":["-updated"]},"explode":false,"style":"form"},{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiAnalysisGroupResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ValidationError"},{"$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"}}}}},"tags":["Analysis Groups"]}}}}
```

## Examples

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

```bash
curl -X GET "https://api.predicthq.com/v1/beam/analysis-groups?status=active&sort=updated" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
```

{% endtab %}

{% tab title="python" %}

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/beam/analysis-groups",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "status": "active",
        "sort": "updated"
    }
)

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


---

# 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/analysis-groups/search-analysis-groups.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.