Skip to main content
Brew Insights watches the brand’s email and records what it finds: deliverability problems, campaigns that did better or worse than usual, timing, and audience and automation opportunities. In the app, the Brew Insights cards on Home open the Insights page. Over the API, 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

It answers 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 answers 400 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 carries freshness, whatever you filter on:
  • dataAsOf is how current the data behind the findings is. It is null before the first successful run.
  • lastSuccessfulRunAt is when the engine last finished a run.
  • latestAttempt is the newest run and its status: succeeded, running, failed, or unknown. A failed attempt 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 the insightId a list row carries.
The answer is the bare finding: the list row’s fields plus these.

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.

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:

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.