Ad-hoc analytics queries tools

execute_analytics_eql: Run a one-off analytics query written in EQL.
estimate_eql_cost: Estimate an EQL query's cost before running it.
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.

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.
`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 and returns pre-warmed results when they're available.

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. 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. When the UI shows populated numbers for the report, this tool returns the same values.

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

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. Validated server-side; an invalid structure returns a 400 error.

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. The shape varies by report type and dimensions. Each entry maps dimension keys to metric values.
`definition`	`any \| null`	The serialized report definition as stored in the project. Useful for understanding the metrics and dimensions behind the result.
`error`	`str \| null`	Error message if the calculation failed.