> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startree.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proactive Analyzer Configuration and Limitations

> Configuration keys, the API endpoints, and current known limitations for Proactive Analyzer.

<Warning>
  **Disabled by default.** Proactive Analyzer is off by default and requires the reactive [Query Analyzer](/corecapabilities/ai/query-analyzer/overview) to be enabled first. Contact your StarTree account team to have it enabled for your environment.
</Warning>

## Enablement

There is no single on/off flag for Proactive Analyzer. It activates when **both** of these are true:

1. The reactive analyzer is on (`query-analyzer.enabled=true`) — Proactive Analyzer reuses the same analysis engine.
2. At least one **delivery target** is configured: a Slack webhook URL or an email recipients list (see below).

If either condition is missing, the scheduled job never loads and the proactive API endpoints are not available.

## Configuration

All keys live under the `query-analyzer.proactive.` prefix:

| Setting | Default | Controls |
| - | - | - |
| `cron` | `0 0 9 * * *` | When the scan runs — daily at 09:00 **UTC** by default |
| `interval` | `PT24H` | The lookback window used to rank queries from the log |
| `query-engines` | `MSE,SSE` | Which query engines are scanned — one ranking pass per engine (multi-stage and single-stage by default) |
| `min-time-used-ms` | `100` | Minimum latency for a query shape to qualify |
| `max-analyses-per-run` | `5` | Cap on analyses **per engine** per run — up to 10 total with the default two engines |
| `system-query-log-table` | `system_query_log` | The query log table the scan reads |
| `notify.slack.webhook-url` | *(empty)* | Slack digest delivery — setting a webhook URL turns Slack delivery on |
| `notify.email.recipients` | *(empty)* | Accepted as a delivery target for activation, but email delivery is not implemented yet |

The skip-when-unchanged behavior (re-analyzing a query shape only when the table configuration has changed since the last analysis) is built in and not configurable.

## API

| Endpoint | Behavior |
| - | - |
| `POST /api/query-analyzer/proactive/run` | Starts one scan immediately on a background thread, without waiting for the schedule. Returns `202 Accepted`, or `409 Conflict` if a scan is already in progress. |
| `GET /api/query-analyzer/proactive/recommendations` | Lists the stored recommendations for the workspace, most expensive first. |
| `GET /api/query-analyzer/proactive/status` | Reports the effective configuration and a summary of the last run — candidates ranked, analyzed, skipped, failed, and the trigger (scheduled or manual). |

## Current Limitations

* **Recommendations are stored in memory** and reset when the service restarts.
* **Scans a single workspace on a single cluster per run.** Multi-cluster and multi-workspace scanning are not yet supported.
* **No automatic ticketing and no dedicated UI.** The digest points a human at the work; it does not file tickets or change any cluster setting on its own.
* **Email delivery is not yet available.** Slack and the log are the supported channels today.

## Related

<Card title="Proactive Analyzer Overview" icon="bell" href="/corecapabilities/ai/query-analyzer/proactive-analyzer/overview">
  What Proactive Analyzer does, how it works, and how it delivers results.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.