Skip to content

analytics_insight_create

Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it.

Tool

analytics_insight_create

Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it.

Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it. Use display bold_number for headline KPIs with dashboard compare, pivot for rows × metrics, line for daily dynamics, and steps for funnels. Give every series a human label when there are several. Filters neq and not_in keep NULL rows. Money stays raw; set the series format {kind: money, scale, currency} so readers see its scale and currency. Each series may have a trimmed display label (1–60 characters). Use series format for display, group_label for a grouped metric's label dimension, and formula_label with formula_format for a named formula. For several formulas use formulas [{key f1..f4, label 1–60, expr, format}] (up to 4) instead of formula — never both (400); each is evaluated exactly as formula is and its number is total[key] (and a pivot cell keyed by it). A percent value is a fraction (0.128 means 12.8%). display facts draws the first series as the base bar (100%) and each next series as a bar with its value and % of the base — use it for independent facts about the same visitors (e.g. base = visited from ads, then reached /pricing, clicked CTA, signed up), unlike steps which are sequential; it is for kind number only (400 otherwise) and runs like any number insight. Chart displays (display-only; refused with 400 at display, stacked or combo when the series cannot be drawn, saying what fits): pie for shares of a whole — one metric series with group_by, or 2–8 ungrouped metric series of one unit (format kind, and currency and scale for money), no percent, no formula; area for volume over time, kind trend only; stacked: true (bar or area only) stacks 2+ series or one grouped series of one unit, no percent, no formula; bar_horizontal for a ranking — one grouped metric series, or 2–8 ungrouped series of one unit (a funnel under kind number counts as its last step), no formula; combo for two scales over time (e.g. cost as bars, signups as a line) — kind trend, 2–4 ungrouped metric series, combo {line: [keys]} names the line series or formulas (default the last series), at least one series stays a bar; all bars must share one unit and all lines one unit (format kind, currency and scale for money; no format is a number), else 400 — move the odd series to the line or split the insight. A number insight may combine a funnel (its value is its last step over the window, ungrouped) with metrics in a formula, e.g. cost per signup = cost / funnel to signup_completed. A single metric series in a trend or number insight may use group_by with per-series top_n (1–20, default 8); grouped insights cannot have a formula. display steps shows a funnel as its steps (persons and conversion per step) and is the default for kind funnel; every other kind defaults to line, and steps is refused on them. Give every funnel step a label (1–60 characters): it is the step's column title and steps label; without one it reads as its entity and filters. A funnel series may set hidden_steps [0-based step indexes] — display-only, e.g. hide the entry step that another funnel already shows: hidden steps still count and every number, formula and total is unchanged; at least one step must stay visible. display pivot is a table of rows per group value across series: every series (a metric, or a funnel by a dimension of its first step) may carry its own group_by; rows are joined by the group value as an exact string. A grouped funnel counts a person in EVERY group they entered by, each from their first entry with that value, so a funnel row equals the same funnel with its first step filtered to that value; rows can overlap and its total is the distinct people (the ungrouped funnel), not the sum of rows. Join keys are exact, so the values must match (events.utm_campaign must equal the Google Ads campaign_id); formula runs per row and over the totals, and a formula or sort names a funnel series by its LAST step only (E means E.<last>); sort {by: series key | formula | f1..f4, dir} and top_n (1–50, default 20) order and cap the rows, the rest fold into other; rows_label (1–40) titles the row-header column. Worked example, the ads campaign table: display pivot, rows_label Кампания, series A label Расход = googleads_campaign_daily cost by campaign_id (format money), B label Клики = clicks by campaign_id, E label Путь = funnel by utm_campaign with steps [{label Уникальные, events page_view}, {label Дошли до /pricing, path starts_with /pricing}, {label Регистрации, signup_completed}], formulas [{key f1, label Цена клика, expr A / B, format money}, {key f2, label Цена регистрации, expr A / E, format money}], sort {by A, dir desc}. The slug is the address the insight is read by and cannot be changed later. A save is refused (400, naming the field to fix) for several series without a label, for display pivot without group_by on any series, and for a series whose request does not suit the kind (series.N.request: trend needs metric requests, number metric or funnel requests, funnel needs funnel requests, retention needs retention requests; only display pivot mixes metric and funnel series) — the same insight would fail to run. Otherwise it returns the stored insight plus warnings[] {code, message, path}: advice that does not block the save — series that differ only in one filter value of a dimension other than event_name, with no group_by yet and not combined by one formula (use group_by or pivot), a formula over money without a money formula_format (or a money formulas entry without a money format), a funnel step without a label (it would show as its entity and filters), a money-looking metric without a unit or series format, a window that starts after today (it has no days yet), a daily table longer than 31 rows (use line). A window.to after today is fine: a run clips it to today, so from a fixed date to a later date is the way to say since <date>. Stores the definition only; it does not run it. Series requests are validated with the same schemas analytics_metric_query and analytics_funnel_run accept, so a stored insight always runs.

Behavior

HTTP
POST /analytics/insights

Arguments

Name
Type
Required
Description
kind
string
•
No description in the catalog.
name
string
•
No description in the catalog.
slug
string
•
No description in the catalog.
sort
object
—
Pivot only: which column orders the rows, and the direction
tags
array
—
No description in the catalog.
combo
object
—
Display combo only: which series draw as the line
grain
string
—
No description in the catalog.
top_n
integer
—
Pivot only: rows kept, 1 to 50 (default 20); the rest are folded into other
series
array
•
No description in the catalog.
target
object
—
No description in the catalog.
window
object
•
No description in the catalog.
display
string
—
How to show the insight. Defaults to steps for a funnel insight, line otherwise. steps is for a funnel only; facts is for kind number only; pivot is a table of rows per group value across series; pie, area, bar_horizontal and combo are refused when the series cannot be drawn that way
formula
string
—
No description in the catalog.
stacked
boolean
—
Display area or bar only: stack the series (or the groups of one grouped series); all in one unit. Defaults to false
formulas
array
—
Up to four named formulas over the series keys, each its own column or line; use instead of formula
rows_label
string
—
Pivot only: the title of the row-header column, 1 to 40 characters (e.g. Кампания)
description
string
—
No description in the catalog.
formula_label
string
—
No description in the catalog.
formula_format
object
—
Display format for a raw value. kind percent means a fraction: 0.128 displays as 12.8%. Money stays raw at the declared scale; readers convert it for display with this format.

Response

Field
Type
Always
Description
id
string
•
kind
string
•
name
string
•
slug
string
•
sort
object
—
Pivot only: which column orders the rows, and the direction
tags
array
—
combo
object
—
Display combo only: which series draw as the line
grain
string
—
top_n
integer
—
Pivot only: rows kept, 1 to 50 (default 20); the rest are folded into other
series
array
•
target
object
—
window
object
•
display
string
—
formula
string
—
stacked
boolean
—
Display area or bar only: stack the series (or the groups of one grouped series); all in one unit. Defaults to false
formulas
array
—
Up to four named formulas over the series keys, each its own column or line; use instead of formula
warnings
array
•
created_at
string
•
created_by
string
•
product_id
string
•
rows_label
string
—
Pivot only: the title of the row-header column, 1 to 40 characters (e.g. Кампания)
updated_at
string
•
description
string
—
formula_label
string
—
formula_format
object
—
Display format for a raw value. kind percent means a fraction: 0.128 displays as 12.8%. Money stays raw at the declared scale; readers convert it for display with this format.

Try it

Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it.

When to use

Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it. Use display bold_number for headline KPIs with dashboard compare, pivot for rows × metrics, line for daily dynamics, and steps for funnels. Give every series a human label when there are several. Filters neq and not_in keep NULL rows. Money stays raw; set the series format {kind: money, scale, currency} so readers see its scale and currency. Each series may have a trimmed display label (1–60 characters). Use series format for display, group_label for a grouped metric's label dimension, and formula_label with formula_format for a named formula. For several formulas use formulas [{key f1..f4, label 1–60, expr, format}] (up to 4) instead of formula — never both (400); each is evaluated exactly as formula is and its number is total[key] (and a pivot cell keyed by it). A percent value is a fraction (0.128 means 12.8%). display facts draws the first series as the base bar (100%) and each next series as a bar with its value and % of the base — use it for independent facts about the same visitors (e.g. base = visited from ads, then reached /pricing, clicked CTA, signed up), unlike steps which are sequential; it is for kind number only (400 otherwise) and runs like any number insight. Chart displays (display-only; refused with 400 at display, stacked or combo when the series cannot be drawn, saying what fits): pie for shares of a whole — one metric series with group_by, or 2–8 ungrouped metric series of one unit (format kind, and currency and scale for money), no percent, no formula; area for volume over time, kind trend only; stacked: true (bar or area only) stacks 2+ series or one grouped series of one unit, no percent, no formula; bar_horizontal for a ranking — one grouped metric series, or 2–8 ungrouped series of one unit (a funnel under kind number counts as its last step), no formula; combo for two scales over time (e.g. cost as bars, signups as a line) — kind trend, 2–4 ungrouped metric series, combo {line: [keys]} names the line series or formulas (default the last series), at least one series stays a bar; all bars must share one unit and all lines one unit (format kind, currency and scale for money; no format is a number), else 400 — move the odd series to the line or split the insight. A number insight may combine a funnel (its value is its last step over the window, ungrouped) with metrics in a formula, e.g. cost per signup = cost / funnel to signup_completed. A single metric series in a trend or number insight may use group_by with per-series top_n (1–20, default 8); grouped insights cannot have a formula. display steps shows a funnel as its steps (persons and conversion per step) and is the default for kind funnel; every other kind defaults to line, and steps is refused on them. Give every funnel step a label (1–60 characters): it is the step's column title and steps label; without one it reads as its entity and filters. A funnel series may set hidden_steps [0-based step indexes] — display-only, e.g. hide the entry step that another funnel already shows: hidden steps still count and every number, formula and total is unchanged; at least one step must stay visible. display pivot is a table of rows per group value across series: every series (a metric, or a funnel by a dimension of its first step) may carry its own group_by; rows are joined by the group value as an exact string. A grouped funnel counts a person in EVERY group they entered by, each from their first entry with that value, so a funnel row equals the same funnel with its first step filtered to that value; rows can overlap and its total is the distinct people (the ungrouped funnel), not the sum of rows. Join keys are exact, so the values must match (events.utm_campaign must equal the Google Ads campaign_id); formula runs per row and over the totals, and a formula or sort names a funnel series by its LAST step only (E means E.<last>); sort {by: series key | formula | f1..f4, dir} and top_n (1–50, default 20) order and cap the rows, the rest fold into other; rows_label (1–40) titles the row-header column. Worked example, the ads campaign table: display pivot, rows_label Кампания, series A label Расход = googleads_campaign_daily cost by campaign_id (format money), B label Клики = clicks by campaign_id, E label Путь = funnel by utm_campaign with steps [{label Уникальные, events page_view}, {label Дошли до /pricing, path starts_with /pricing}, {label Регистрации, signup_completed}], formulas [{key f1, label Цена клика, expr A / B, format money}, {key f2, label Цена регистрации, expr A / E, format money}], sort {by A, dir desc}. The slug is the address the insight is read by and cannot be changed later. A save is refused (400, naming the field to fix) for several series without a label, for display pivot without group_by on any series, and for a series whose request does not suit the kind (series.N.request: trend needs metric requests, number metric or funnel requests, funnel needs funnel requests, retention needs retention requests; only display pivot mixes metric and funnel series) — the same insight would fail to run. Otherwise it returns the stored insight plus warnings[] {code, message, path}: advice that does not block the save — series that differ only in one filter value of a dimension other than event_name, with no group_by yet and not combined by one formula (use group_by or pivot), a formula over money without a money formula_format (or a money formulas entry without a money format), a funnel step without a label (it would show as its entity and filters), a money-looking metric without a unit or series format, a window that starts after today (it has no days yet), a daily table longer than 31 rows (use line). A window.to after today is fine: a run clips it to today, so from a fixed date to a later date is the way to say since <date>. Stores the definition only; it does not run it. Series requests are validated with the same schemas analytics_metric_query and analytics_funnel_run accept, so a stored insight always runs.

Example

Ask your agent something like this:

Save a named insight for the current product: one to eight series over the analytics semantic layer, an optional formula combining them by key, a time window and how to display it.

The agent will invoke analytics_insight_create with these arguments:

{
  "kind": "<kind>",
  "name": "<name>",
  "slug": "<slug>",
  "series": "<series>",
  "window": "<window>"
}

Esc

Start typing to search the docs.

↑↓navigate↵select