Skip to main content
Availability: Deep research is a Beta feature available on Enterprise plans. It is behind a feature flag. Contact Lightdash to enable it for your organization.
Deep research is a long-running mode for Lightdash AI agents. It is designed for questions that need several queries, competing explanations, and a reusable report rather than one immediate answer. The agent investigates in the background using its Lightdash context and configured sources. It returns a structured Markdown report with confidence levels, supporting charts, citations for external sources, and explicit caveats.
Ask AI composer with Deep research mode enabled and highlighted by an arrow

​
When to use deep research

Use deep research

Choose this mode for multi-step investigations that need cross-checking, several data cuts, or a report you can save and revisit.

Use Ask mode

Stay in the default mode for a quick lookup, one chart, or an interactive conversation where you want to steer each follow-up.
Questions that work well include:
  • “Which product categories are trending down this quarter, and what is driving the change?”
  • “Why did returning-customer revenue fall over the last 90 days? Test the main explanations.”
  • “Compare paid and organic acquisition quality across our top three regions.”

​
How it works

Deep research uses the selected AI agent’s configuration, including its instructions, semantic-layer access, knowledge documents, project and repository context, and enabled tools. It automatically inherits the organization’s research limits and every MCP server attached to the agent; there is no per-run depth or source selection. For each run, a coordinator owns the investigation: it gathers context, queries the data, and decides what to pursue next. When a question is genuinely separable it can hand that question to an isolated data worker, up to two per run. A worker sees only its own task and warehouse tools, and returns a compact findings packet rather than raw results. The coordinator does not write the report. When research ends, Lightdash rebuilds what the run established from the queries it actually ran and their results, and the report is written from that evidence. This keeps the report grounded in verified executions and means a run that stops early still reports what it found. Because the run executes on the server, you can close the tab or leave the thread. Reopening the thread restores the run card and its latest state.

​
Start a run

1

Open Ask AI

Use the Ask AI composer on the homepage, start a new agent thread, or open an existing thread that you own. Deep research is unavailable in read-only threads, such as another user’s thread or a thread started in Slack.
2

Enable Deep research

Select Deep research in a new conversation, or select the telescope icon in an existing conversation. The control changes color when the mode is active.
3

Describe the outcome you need

Include the decision or question, relevant time period, important segments, and any definitions or constraints the agent should preserve.
4

Start the investigation

Submit the question. Lightdash saves it in the thread, creates a durable run, and begins processing it in the background.

​
Organization-wide limits

Organization admins set the safety limits inherited by every deep research run. Go to Organization settings → Ask AI → Deep research to configure:
  • Maximum steps — model steps the coordinator may take before it must finish
  • Maximum tool calls — total tool calls across the coordinator and its workers
  • Maximum warehouse queries — total semantic-layer and SQL queries across the run
  • Time limit (ms) — wall-clock ceiling for the research phase
  • Maximum tokens — total model tokens across the run
Each limit must be a positive whole number. Defaults are 16 steps, 24 tool calls, 15 warehouse queries, a 10-minute time limit, and 10 million model tokens. Organization admins can change these values to match their governance and cost requirements. Limits apply to the run as a whole, not to each worker separately. Well before a ceiling, a run stops widening its investigation and starts settling on an answer, so it usually finishes on its own rather than being cut off. When a run does reach a limit, Lightdash still writes the report from the evidence gathered up to that point and marks the run as partially completed.

​
Sources and permissions

Deep research can use:
  • Agent context and project data — the semantic layer, saved Lightdash content, knowledge documents, and other context configured on the selected agent, subject to its data access settings.
  • Warehouse queries — semantic queries and, when the agent and user are allowed to use it, SQL.
  • Repository context — project context and source-code tools configured on the agent.
  • MCP servers — every server attached to the agent and its enabled tools.
Deep research runs without pausing for approval on each warehouse query or MCP tool call. An attached MCP server can expose write actions, and its enabled actions can run unattended. Review the agent’s attached servers and enabled tools before starting a run.
Deep research does not grant new permissions. The run starts with the creator’s access and the selected agent’s configuration, and Lightdash revalidates that access while the investigation runs. Revoking access or disconnecting a source can stop an active investigation or leave that source unavailable.

​
Follow progress

The run card stays next to the question that started it and shows the latest phase, elapsed time, warehouse-query count, finding count, and recent activity.
Lightdash accepted the run and is waiting for a background worker to start it.
The agent is gathering context, querying the data, or writing the report. Select View activity to inspect recent progress.
The full report is ready and saved in the thread.
The run reached a resource limit or recoverable error. Lightdash still wrote the report from the evidence gathered before it stopped.
The run could not produce a valid report. The run card keeps completed activity and provides safe retry guidance.
The creator stopped the run before it finished.
Select Stop research while a run is queued or running to request cancellation. Cancellation is asynchronous, so a running tool call may reach its next safe checkpoint before the status changes. Only one deep research run can be active in a thread at a time. While it is active, the deep research control is disabled, but you can continue sending regular chat messages in the same thread. The control becomes available again when the run completes, partially completes, fails, or is cancelled.

​
Read the report

Select Open full report from a completed or partially completed run card. A report contains:
Deep Research report comparing pull request volume and merge rates across engineering teams, with confidence labels and a chart snapshot
  • A direct introduction that answers the question and states overall confidence
  • Two to five connected finding sections, each with a low, medium, or high confidence level
  • Charts, each backed by a query the run executed, when visual evidence improves the explanation
  • Caveats where data coverage, freshness, or the semantic layer limits the conclusion
  • A conclusion and citations for external evidence
Confidence reflects the evidence available to the agent, not a guarantee that the conclusion is correct. Review the definitions, assumptions, and supporting queries before making a high-impact decision.

​
Chart snapshots and live data

Warehouse-backed charts open on a snapshot of the data the agent used when it wrote the report. This preserves the original evidence even if the underlying data changes later. Every report chart is backed by one warehouse query the run actually executed, so any chart can be refreshed. Select Live data on a chart to rerun its stored query and compare the latest result with the snapshot.

​
Report retention

Deep research report content and chart snapshots expire 30 days after the run completes. The run’s question, status, and completion date remain in the thread. After expiry, select Run again to start a new investigation from the original question using the agent’s current configuration and the organization’s current limits. The regular chat agent can use the status and report from deep research runs in the same conversation when answering follow-up questions. Ask it to clarify a finding, compare evidence, or explain a limitation without pasting the report back into the chat.

​
Get better reports

  • State the decision you are trying to make, not only the metric you want to inspect.
  • Define ambiguous terms such as active customer, conversion, or retention.
  • Include the time range and comparison period.
  • Name segments the agent must test, such as channel, region, plan, or product category.
  • Ask it to test alternatives or contradictions instead of assuming one cause.
  • Treat a partially completed report as a starting point. Resolve unavailable sources or tighten the question before running it again; ask an organization admin to review the limits if runs repeatedly exhaust them.

​
Access requirements

Starting a run requires the Enterprise Start Deep Research runs scope (create:AiDeepResearch) for the project. Developer and Admin roles receive this scope by default. Add it explicitly to any custom role that should be allowed to start runs. Users can only read, retry, or cancel their own deep research runs, and only within threads they are allowed to access.

​
Frequently asked questions

Do I have to keep the tab open? No. The run continues on the server and its state is saved in the thread. Can I start deep research in an existing conversation? Yes. You can start a run from an existing thread you own as long as the thread is not read-only and the agent’s model is still available. Can I start another run while research is still active? Not in the same thread. You can keep chatting normally, or start deep research in another eligible thread. The control returns when the current run reaches a terminal state. Why did my run partially complete? The agent reached a resource budget or encountered a recoverable failure. Because the report is written from the queries the run executed rather than assembled as it goes, Lightdash still reports what the run established instead of discarding it. Does deep research only read data? No. It uses the selected agent’s configured tools. Warehouse queries run without individual approval, and attached MCP servers may include write actions. Review the agent’s configuration before starting. Can I continue chatting after the report is ready? Yes. The report remains available in the thread for 30 days, and the same agent can use it as context for follow-up questions.