Reports tools
The reports and manage_report tools open, run and build the reports in the Reports section of the vyg.ai app.
Two tools on https://api.vyg.app/mcp cover reports:
| Tool | Kind | Actions |
|---|---|---|
reports | read | list, get, run, events, samples, preview |
manage_report | write | create, update, duplicate, delete |
Reports need customer data (CDP) access for your brand. Reading needs insights:read; saving, changing and
deleting custom reports needs insights:write.
reports: list
list returns every report your brand can open: your own custom reports and reports VYG made for you first, then
the built-in ones. Each report says whether it is ready, which inputs it takes (a date range, a comparison or an
attribution window) and whether you can change it.
{ "action": "list" }"What reports do I have?"
reports: get
get takes a report id from list and returns the report with how its numbers are counted.
{ "action": "get", "id": "revenue-overview" }reports: run
run returns a report's columns, rows and totals. Only a report whose status is ready in list can be run; one
marked soon answers "Report not found". Pass from and to (YYYY-MM-DD, UTC, inclusive) for a report with a
date range, compare: "previous_period" to also total the same number of days before, and window for a report
that lists the attribution window among its inputs. sort and limit shape the rows.
A result is kept for one hour. Asking again for the same report and inputs inside that hour returns the saved
result; refresh: true reads the data again, at most once a minute.
{ "action": "run", "id": "revenue-overview", "from": "2026-10-01", "to": "2026-10-31", "compare": "previous_period" }"How did revenue do last month compared with the month before?"
reports: events and samples
A custom report counts one event. events lists the events your brand has, grouped by where they come from (your
store, your website, connected apps and custom data sources), with their properties and how often each happened in
the last 30 days. Some events in that list cannot be used in a custom report yet (for example placed orders and
abandoned checkouts, which are answered from order and checkout state), and a report cannot filter by product or
collection; preview and create say so in plain words when that happens.
samples shows a few recent occurrences of one event, by its event id from events, with its fields and example
values. Use it to check what an event looks like before you build a report on it. count sets how many, 1 to 10
(default 5).
{ "action": "samples", "event": "pixel.checkout_started", "count": 5 }reports: preview
preview counts a draft custom report definition (see manage_report below) for a from/to range and returns
the same columns, rows and totals a saved report would. Nothing is saved.
{
"action": "preview",
"definition": {
"source": "events",
"event": "pixel.checkout_started",
"measure": "customers",
"breakdown": "week"
},
"from": "2026-09-01",
"to": "2026-10-31"
}"How many customers started a checkout each week since September?"
manage_report
Pick the change with op. A custom report definition is:
| Field | What it sets |
|---|---|
source | Always "events". |
event | The event id from reports action events. |
measure | "events" counts how many times it happened; "customers" counts customers. |
breakdown | "day", "week" or "month" (UTC). |
filters | Optional, up to 10 { property, op, value } on the event's properties. |
createsaves a custom report with aname, an optionaldescriptionandcategory, and thedefinition.updatechanges a custom report'sname,description,categoryordefinition, byid.duplicatecopies a custom report, byid.deleteremoves a custom report permanently, byid.
Only your brand's own custom reports can be changed. Built-in reports and reports VYG made for you are read-only.
{
"op": "create",
"name": "Weekly checkout starters",
"definition": { "source": "events", "event": "pixel.checkout_started", "measure": "customers", "breakdown": "week" }
}"That looks right. Save it as a report called Weekly checkout starters."