Skip to main content
This page explains what the insights step does. For the fields it takes, and which are required, see Step types.
An insights step asks a natural-language question about your project and returns a structured answer that matches a schema you define. Behind it is a dedicated analytics agent that looks up and analyzes your commerce metrics, interprets what it finds, and fills in the output you asked for. On the canvas the step appears as Insights Agent. Use insights when a step needs a computed metric or aggregate to make its decision: this week’s revenue, the top-selling products over a window, or repeat-purchase rate by cohort. The agent does the analysis; the rest of the automation acts on the answer.

​
What it can answer

The insights step runs the same analytics agent that powers insights in chat. It answers aggregate questions over your project’s commerce data: totals, trends, top-N rankings, period-over-period comparisons, cohorts, and funnels across orders, revenue, customers, and products. It applies the correct commerce definitions itself, so you ask in plain language instead of spelling out formulas. The step is read-only. It looks up and analyzes metrics and returns figures.

​
Writing the question

Ask in plain language, the way you would ask an analyst. The agent owns the metric definitions, so you do not need to specify formulas, status breakdowns, or output formatting. Reference event and earlier-step data with data access variables, and fold related metrics into a single question rather than splitting them across steps. If the project has run out of usage credits, the agent is paused instead of failing.

​
Verify entities before acting on them

Insights reads from your project’s event history. History can name products or customers that no longer exist in the catalog. Aggregate figures need no verification. Entity references do. When a downstream step features, messages about, or updates entities the insights step named, give that step the matching read tools and tell it to verify each one. Ask insights for a few extra entities (top 8 for a top 5) so skipped ones leave no gap.

​
Use cases

  • Weekly digest: an insights step computes {revenue, order_count, aov}, a downstream action posts it to Slack.
  • Restock signal: an insights step returns the top-selling products over a window, a map step runs a restock action per item.
  • Threshold gate: an insights step returns a metric, a choice step branches when it crosses a threshold.
  • Best-sellers page: insights ranks products, Custom agent writes the copy, a storefront builder step updates the page.

​
Next steps