# Get Correlation Results ## Get Correlation Results > Retrieve results of the correlation of our event data with your transactional demand data. ```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 ` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"parameters":{"OffsetParam":{"name":"offset","in":"query","description":"Offset the results.","required":false,"schema":{"type":"integer","default":0}}},"schemas":{"MultiDerivativeResponse":{"description":"Please note we have deprecated some fields in this endpoint. The deprecated fields are not intended \nto be used to get current feature values for use in forecasting or other use-cases. They're a snapshot of \nsome of the data from the time the correlation process was run, so for any other purposes are immediately \nout-of-date. Please fetch the latest data from Features API instead.","type":"object","properties":{"model_version":{"description":"The version identifier of the model used for the decomposition.","type":"string","title":"Model Version"},"version":{"description":"The version number of the correlation data.","type":"integer","title":"Version"},"count":{"description":"Total number of correlation result records.","type":"integer","title":"Count"},"dates":{"description":"The list of correlation results per date.","type":"array","items":{"$ref":"#/components/schemas/DemandDerivativeResponse"},"title":"Dates"}},"required":["model_version","version","count","dates"],"title":"MultiDerivativeResponse"},"DemandDerivativeResponse":{"type":"object","properties":{"date":{"description":"The date of the Beam decomposition.","type":"string","title":"Date"},"baseline_demand":{"description":"The expected demand for a given date.","type":"number","title":"Baseline Demand"},"remainder":{"description":"The difference between the actual_demand and the baseline_demand for a given date. This value may be positive or\nnegative.","type":"number","title":"Remainder"},"actual_demand":{"description":"The actual demand for a given date.","type":"number","title":"Actual Demand"},"impact_significance":{"description":"Enum specifying how unusual the remainder is for a given date.","type":"string","enum":["NO_IMPACT","WEAK","MEDIUM","SIGNIFICANT"],"title":"Impact Significance"},"impact_significance_score":{"description":"Number specifying how unusual the remainder is for a given date. This value maps to `impact_significance`.","type":"integer","enum":[0,1,2,3],"title":"Impact Significance Score"},"features":{"description":"A json object containing all non-zero features for a given date.","type":"object","additionalProperties":true,"deprecated":true,"title":"Features"},"phq_impact_sum":{"description":"The sum of all phq_impact features for a given date.","type":"integer","deprecated":true,"title":"Phq Impact Sum"},"phq_spend_sum":{"description":"The sum of all phq_spend features for a given date.","type":"integer","deprecated":true,"title":"Phq Spend Sum"},"phq_attendance_sum":{"description":"The sum of all phq_attendance features for a given date.","type":"integer","deprecated":true,"title":"Phq Attendance Sum"},"phq_rank_count":{"description":"The sum of all phq_rank features for a given date.","type":"integer","deprecated":true,"title":"Phq Rank Count"}},"required":["date","impact_significance"],"title":"DemandDerivativeResponse"},"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"}}},"paths":{"/v1/beam/analyses/{analysis_id}/correlate":{"get":{"operationId":"get_analysis_correlation","summary":"Get Correlation Results","description":"Retrieve results of the correlation of our event data with your transactional demand data.","parameters":[{"name":"analysis_id","in":"path","description":"An existing Beam Analysis ID.","required":true,"schema":{"type":"string"}},{"name":"date.gt","in":"query","description":"Filters results after the specified date (exclusive).","required":false,"schema":{"type":"string","format":"date"}},{"name":"date.gte","in":"query","description":"Filters results on or after the specified date.","required":false,"schema":{"type":"string","format":"date"}},{"name":"date.lt","in":"query","description":"Filters results before the specified date (exclusive).","required":false,"schema":{"type":"string","format":"date"}},{"name":"date.lte","in":"query","description":"Filters results on or before the specified date.","required":false,"schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/OffsetParam"},{"name":"limit","in":"query","description":"Limit the number of results.","required":false,"schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiDerivativeResponse"}}}},"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"}}}},"404":{"description":"Analysis or Derivative not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPError"}}}},"500":{"description":"Internal inconsistency detected. Please refresh the analysis"}},"tags":["Analyses"]}}}} ``` ## Examples {% tabs %} {% tab title="curl" %} ```bash curl -X GET "https://api.predicthq.com/v1/beam/analyses/$ANALYSIS_ID/correlate?date.gte=2022-01-01&date.lte=2022-12-31" \ -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/correlate", headers={ "Authorization": "Bearer $API_TOKEN", "Accept": "application/json" }, params={ "date.gte": "2022-01-01", "date.lte": "2022-12-31" } ) 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-correlation.md?ask= ``` 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.