VYG Docs
Tools

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:

ToolKindActions
reportsreadlist, get, run, events, samples, preview
manage_reportwritecreate, 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:

FieldWhat it sets
sourceAlways "events".
eventThe event id from reports action events.
measure"events" counts how many times it happened; "customers" counts customers.
breakdown"day", "week" or "month" (UTC).
filtersOptional, up to 10 { property, op, value } on the event's properties.
  • create saves a custom report with a name, an optional description and category, and the definition.
  • update changes a custom report's name, description, category or definition, by id.
  • duplicate copies a custom report, by id.
  • delete removes a custom report permanently, by id.

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."

On this page