---
updatedAt: 2026-09-17T18:41:17.000Z
agentTools:
  siteIndex: https://documentation.bloomreach.com/llms.txt
  projectIndex: https://documentation.bloomreach.com/loomi-connect/llms.txt
---

# Ad-hoc analytics queries tools

* [execute\_analytics\_eql](#execute_analytics_eql): Run a one-off analytics query written in EQL.
* [estimate\_eql\_cost](#estimate_eql_cost): Estimate an EQL query's cost before running it.
* [calculate\_report](#calculate_report): Run a saved report by ID and return its computed results.

## execute\_analytics\_eql

Runs an ad-hoc analytics query written in EQL (Exponea Query Language) against a project. Nothing is saved in the project — the result is computed and returned.

The query must be a `select` report query or a `funnel` query. Examples:

* `select count customers by customer.country`
* `select sum event purchase.revenue`
* `funnel session_start followed by purchase`

Standalone metric expressions (such as `count event purchase`) are not executable on their own. Wrap them in a select, like `select count event purchase`.

EQL parse errors are returned as `success: false` with the parser's message in the `error` field — they are not raised as exceptions.

### Match customers on event absence

Questions like "who bought but never consented" depend on matching customers by an event they didn't trigger. The idiom for that is `not exists[event X]` inside a `customers matching` clause, and its counterpart `exists[event X]` matches customers who did trigger the event. Examples:

* `customers matching not exists[event purchase]` matches customers with no purchase event at all.
* `customers matching not exists[event purchase in last 30 days]` bounds the absence to a window, so it matches customers who haven't purchased recently even if they purchased long ago.
* `customers matching exists[event purchase] and not exists[event consent where .action = "accept"] and not exists[event consent where .action = "reject"]` matches customers who bought something but never accepted or rejected consent — the audience to review before a re-permissioning campaign.

Wrap the same clause in a `select` to size the audience or break it down over time, for example `select count customers by any event timestamp format year month customers matching exists[event purchase] and not exists[event consent] in last 12 months`.

> 📘 Note
>
> `not exists[...]` works in a `customers matching` clause, because customer filters support full boolean logic including negation. It doesn't work in a `where` event filter, which accepts only `and`-joined conditions. Inside a `where` clause, express absence as `count[...] = 0` instead.

### Request parameters

| Name             | Type          | Required? | Description                                                                                                                                                                                  |
| :--------------- | :------------ | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`     | `str`         | Yes       | The project ID returned by `list_projects`.                                                                                                                                                  |
| `query`          | `str`         | Yes       | The EQL query string. Must be a `select` report query or a `funnel` query. A `customers matching` clause supports full boolean logic, including `exists[event X]` and `not exists[event X]`. |
| `execution_time` | `int \| null` | No        | A Unix timestamp (in seconds) used as the upper boundary for events to consider. Defaults to the current time.                                                                               |

### Response parameters

The tool returns an `EqlExecutionResponse` object with the following parameters:

| Parameter       | Type          | Description                                                                                                                                                         |
| :-------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `success`       | `bool`        | Whether the query was parsed and computed successfully.                                                                                                             |
| `query`         | `str`         | The EQL query string that was executed.                                                                                                                             |
| `analysis_type` | `str \| null` | The analysis type inferred from the EQL query: `report`, `trend`, or `funnel`. Null if parsing failed before the type could be determined.                          |
| `data`          | `any \| null` | The computed result. The shape depends on `analysis_type`. For reports: rows with headers and metric values. For funnels: step-by-step conversion counts and rates. |
| `error`         | `str \| null` | Error message if parsing or computation failed.                                                                                                                     |

## estimate\_eql\_cost

Parses an EQL query and estimates its cost without running it. The response gives you a score from 0 to 100, a bucketed level, the factors that drive the cost, and suggestions for bringing it down.

Use this before `execute_analytics_eql` when you're unsure whether a query will pass the cost limit, or when you want to compare the cost of query variants before you commit to one. The cost score is structural: it models the query shape, such as date range, funnel steps, breakdowns, and filter complexity, but doesn't account for the project's actual data volume.

This tool is in alpha, so its API or response shape may change.

### Request parameters

| Name         | Type  | Required? | Description                                                                         |
| :----------- | :---- | :-------- | :---------------------------------------------------------------------------------- |
| `project_id` | `str` | Yes       | The project ID returned by `list_projects`.                                         |
| `query`      | `str` | Yes       | The EQL query string to estimate, using the same syntax as `execute_analytics_eql`. |

### Response parameters

The tool returns an `EqlCostEstimate` object with the following parameters:

| Parameter     | Type        | Description                                                                                                                                         |
| :------------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| `score`       | `int`       | The structural cost score from 0 to 100. Higher means more expensive. Based on query shape only.                                                    |
| `level`       | `str`       | The bucketed level: `low` (0–15), `medium` (16–35), `high` (36–60), or `very_high` (61–100).                                                        |
| `factors`     | `list[str]` | The cost-contributing factors found in the query structure, for example `lifetime date range`, `3-step funnel`, or `unbounded breakdown dimension`. |
| `suggestions` | `list[str]` | Actionable fixes for each factor, for example `add 'in last N days' to bound the scan` or `add 'grouping top 10' after each 'by' clause`.           |

## calculate\_report

Runs a saved report by ID and returns its computed results. Unlike `execute_analytics_eql`, which always recomputes from scratch, this tool routes through the analysis cache by default and returns pre-warmed results when they're available.

The report must already exist in the project. Use `search_reports` to browse available reports and find the `report_id`.

This is the right tool for reports that contain running aggregates. Computing running aggregates on demand is expensive, but the platform's periodic recalculation keeps saved reports warm, so their results are ready right away. When the UI shows populated numbers for the report, this tool returns the same values.

<Callout icon="🚧" theme="warn">
  ### Warning

  Cached results depend on the cache being warm. If the report has never been opened or calculated in the UI, the cache may be cold, and results will be empty or stale.
</Callout>

Parametrized reports need a second step. When `search_reports` shows `parametrized` as `true`, pass `parameter_values` with a value for each name in the report's `parameters` list. Doing so switches the calculation to the live preview path instead of the cache, so the values apply to that one calculation and are never written back to the saved report.

<Callout icon="🚧" theme="warn">
  ### Warning

  The `global_filters` parameter can't supply parameter values. If a parametrized report is calculated without them and nothing is stored on the report, the response comes back with `success` as `false` and an `error` that names the missing parameter, for example `Missing value for parameter 'banner_name'`.
</Callout>

### Request parameters

| Name               | Type                     | Required? | Description                                                                                                                                                                                                                                                                           |
| :----------------- | :----------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id`       | `str`                    | Yes       | The project ID returned by `list_projects`.                                                                                                                                                                                                                                           |
| `report_id`        | `str`                    | Yes       | The report ID returned by `search_reports`.                                                                                                                                                                                                                                           |
| `execution_time`   | `int \| null`            | No        | A Unix timestamp (in seconds) used as the upper boundary for events to consider. Defaults to the current time.                                                                                                                                                                        |
| `global_filters`   | `dict \| null`           | No        | Optional global filters to apply to the analysis. Supports date-range narrowing and customer attribute value filters. Can't supply values for a parametrized report's parameters — use `parameter_values` for those. Validated server-side; an invalid structure returns a 400 error. |
| `parameter_values` | `dict[str, str] \| null` | No        | Runtime values for a parametrized report, as a map of parameter name to string value. Use the names from `search_reports` `parameters`. Merged over any values stored on the report, and not persisted.                                                                               |

### Response parameters

The tool returns a `CalculateReportResponse` object with the following parameters:

| Parameter    | Type          | Description                                                                                                                                                                                                                                                                                                                                 |
| :----------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `success`    | `bool`        | Whether the calculation succeeded.                                                                                                                                                                                                                                                                                                          |
| `as_dict`    | `any \| null` | The computed report data. Without `parameter_values`, a flattened map of dimension keys to metric values from the cache path. With `parameter_values`, the hierarchical preview result, the same shape family as `execute_analytics_eql`.                                                                                                   |
| `definition` | `any \| null` | The report definition in the same agent-facing shape as `search_reports` detail mode: the `server` analysis body plus parameter metadata, with chart and table display settings and per-metric UI modifiers stripped. With `parameter_values`, the `parameter_values` it reports are the merged runtime values rather than the stored ones. |
| `error`      | `str \| null` | Error message if the calculation failed. Errors are classified, for example `[SERVICE_UNAVAILABLE]`, and carry a plain-language reason, so a rejected calculation names what went wrong instead of returning a bare 400. An outage or authentication failure does not include the raw upstream response body.                               |

<br />