GET /v1/insights lists the findings as that page ranks them, and
GET /v1/insights/{insightId} reads one in full.
Both reads are free, need the emails scope, and count against the
analytics.read rate limit. An
organization key names the brand with X-Brand-Id, as on every
brand-scoped route.
The API only reads. You start a run by hand in the app, where it opens
a Brew chat and uses credits.
List the Findings
200 with { data, pagination, freshness }, most severe first
and then by score:
description is the detector’s own headline. Quote it rather than restating
its numbers. kind says what sort of finding it is: answer reports what
happened, insight is a change that passed its statistical test, and
strategy is a recommended next step. action, when present, either links
to a page in Brew (navigate) or carries the request the Insights page
would send to Brew’s assistant (assistant, with intent and prompt).
When the Findings Change Mid-Walk
The list is ranked again on every request, so it can change between pages. A refused page answers400 INVALID_REQUEST with param: "cursor". Read
again from the first page with the same state and severity.
Cursor Semantics owns the
rule.
Check Freshness Before You Report
Every page carriesfreshness, whatever you filter on:
dataAsOfis how current the data behind the findings is. It isnullbefore the first successful run.lastSuccessfulRunAtis when the engine last finished a run.latestAttemptis the newest run and itsstatus:succeeded,running,failed, orunknown. Afailedattempt means the findings may be stale, so say so when you report them.
Add the Intelligence Layer
include adds what the Insights page shows beside the findings. Each
expansion is a top-level key on the page. pulse, report, and memo are
null until they exist, and suggestions is an empty array when there are
none.
measured: false means open and click measurements are unavailable.
Hide their counts and rates, including numeric zeros, without inferring that
domain tracking is off. When measured is true, zero is still a value.
The expansions describe the brand, not the page, so they are the same on
every page. Ask for them on the first page only.
Read One Finding
Pass theinsightId a list row carries.
Errors
From an Agent
Over MCP,list_insights reads the same
findings, and include is an array (include: ["pulse", "report"]). Pass an
insightId from a row (not a report insight key) and list_insights returns
that one finding in full, with its frozen metrics, evidence and detector
method, as GET /v1/insights/{insightId} does. insightId cannot be combined
with state, severity, include, limit or cursor.
list_insights trims long text and cuts its expansions to fit one tool
result, and a truncated array names each cut;
MCP Page Sizes owns that
rule. The HTTP read always answers whole.
From the shell, brew-cli insights list takes
--state, --severity, and --include, and --all returns every finding
with the expansions from the first page.
Related
- List insights and Get an insight in the Public API v1 reference: every field and its schema.
- Pagination: the cursor envelope and the MCP page sizes.
- Errors: the error envelope and every code.
- Reading Analytics: the sends and events behind the findings.
Need Help?
Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:- Self-Service Tools
- Talk to Our Team
Search Documentation
Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.
Ask ChatGPT or Claude
Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.