VYG Docs

Insights

GET/v1/insights/ltv

Scope: insights:read.

See total and average customer spending, with a breakdown by spend range.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/ltv"
{  "scope": "string",  "total_revenue": "string",  "customer_count": 0,  "average_ltv": "string",  "currency_code": "string",  "distribution": [    {      "label": "string",      "min": 0,      "max": 0,      "customer_count": 0    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/ltv-by-year

Scope: insights:read.

See total completed-order revenue per calendar year for the last 5 years, in the primary currency.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/ltv-by-year"
{  "scope": "string",  "currency_code": "string",  "coverage_from": "string",  "years": [    {      "year": 0,      "total_revenue": "string"    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/rfm

Scope: insights:read.

See customer groups based on how recently they bought, how often they buy and how much they spend. Use as_of as the date for measuring time since the last purchase; the default is now.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

as_of?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/rfm"
{  "scope": "string",  "as_of": "string",  "customer_count": 0,  "distribution": [    {      "tier": "string",      "customer_count": 0,      "share": 0    }  ],  "definitions": [    {      "tier": "string",      "description": "string",      "rule": "string"    }  ],  "grid": [    {      "recency_score": 0,      "frequency_score": 0,      "customer_count": 0    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/products

Scope: insights:read.

See top products by revenue and order count, based on completed orders. The default period is the 30 days ending at created_at_lte, or today if omitted. Date ranges longer than 31 days return bad_request.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

created_at_gte?string|null
created_at_lte?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/products"
{  "scope": "string",  "top_by_revenue": [    {      "product_id": "string",      "title": "string",      "quantity": 0,      "order_count": 0,      "customer_count": 0,      "revenue": "string",      "repeat_purchase_rate": 0    }  ],  "top_by_order_count": [    {      "product_id": "string",      "title": "string",      "quantity": 0,      "order_count": 0,      "customer_count": 0,      "revenue": "string",      "repeat_purchase_rate": 0    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/at-risk

Scope: insights:read.

Find repeat customers who are overdue for their next order. Includes customers with purchases on at least two different days who have gone more than twice their usual interval without ordering. Use as_of as the date for measuring time since the last purchase; the default is now.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer
cursor?string|null
as_of?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/at-risk"
{  "data": [    {      "contact_id": "string",      "name": "string",      "email": "string",      "phone": "string",      "external_id": "string",      "last_order_at": "string",      "days_since_last_order": 0,      "median_inter_order_days": 0,      "brand_median_inter_order_days": 0,      "at_risk": true,      "at_risk_score": 0    }  ],  "next_cursor": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/lifecycle

Scope: insights:read.

See lifecycle stage counts (Visitors, Customers, Repeat Customers, and more) read from the brand seeded lifecycle segments, with conversion ratios between adjacent stages.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/lifecycle"
{  "stages": [    {      "node": "string",      "segment_id": "string",      "name": "string",      "member_count": 0,      "evaluated_at": "string",      "state": "evaluating",      "delta_30d": 0    }  ],  "edges": [    {      "from": "string",      "to": "string",      "ratio": 0    }  ],  "archived_stages": [    "string"  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/overview

Scope: insights:read.

See active buyers, average order value, orders per customer and total value for a 7, 30 or 90 day window, with the previous window for comparison, daily series for both windows and the new vs returning customer value split.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

window_days?string|null
segment?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/overview"
{  "window_days": 0,  "segment": "all",  "currency_code": "string",  "coverage_from": "string",  "active_buyers": 0,  "average_order_value": "string",  "orders_per_customer": 0,  "total_value": "string",  "previous_active_buyers": 0,  "previous_average_order_value": "string",  "previous_orders_per_customer": 0,  "previous_total_value": "string",  "series": [    {      "date": "string",      "active_buyers": 0,      "orders": 0,      "total_value": "string",      "average_order_value": "string",      "orders_per_customer": 0    }  ],  "previous_series": [    {      "date": "string",      "active_buyers": 0,      "orders": 0,      "total_value": "string",      "average_order_value": "string",      "orders_per_customer": 0    }  ],  "revenue_split": {    "new_value": "string",    "returning_value": "string",    "new_buyers": 0,    "returning_buyers": 0,    "previous": {      "new_value": "string",      "returning_value": "string",      "new_buyers": 0,      "returning_buyers": 0    }  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/product-performance

Scope: insights:read.

See per-product viewers, add to cart, checkouts, orders, buyers, units and gross sales for a 7, 30 or 90 day window with the previous window for comparison, the store conversion funnel of people from a page view through each checkout step, and completed orders beside it.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

window_days?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/product-performance"
{  "window_days": 0,  "currency_code": "string",  "browse_coverage_from": "string",  "products": [    {      "product_id": "string",      "title": "string",      "image_url": "string",      "viewers": 0,      "add_to_cart": 0,      "checkouts": 0,      "orders": 0,      "buyers": 0,      "units": 0,      "revenue": "string",      "previous": {        "viewers": 0,        "add_to_cart": 0,        "checkouts": 0,        "orders": 0,        "buyers": 0,        "units": 0,        "revenue": "string"      }    }  ],  "funnel": {    "visits": 0,    "product_views": 0,    "add_to_cart": 0,    "checkout_started": 0,    "contact_info": 0,    "address_info": 0,    "shipping_info": 0,    "payment_info": 0,    "checkout_completed": 0,    "purchases": 0,    "orders_in_period": 0,    "previous": {      "visits": 0,      "product_views": 0,      "add_to_cart": 0,      "checkout_started": 0,      "contact_info": 0,      "address_info": 0,      "shipping_info": 0,      "payment_info": 0,      "checkout_completed": 0,      "purchases": 0,      "orders_in_period": 0,      "counted_from": "string"    },    "counted_from": "string"  },  "order_history_from": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/first-product

Scope: insights:read.

See which products customers buy first: the top 10 line-item titles from each customer's earliest completed order, with a count and share of all purchasing customers.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/first-product"
{  "denominator": 0,  "products": [    {      "title": "string",      "count": 0,      "share": 0    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/sources

Scope: insights:read.

See where first orders come from: customers counted by the utm_source of their earliest completed order, falling back to referrer_host, then the first captured website touch, then 'direct'. Top 8 raw sources plus 'other', and the same customers grouped into marketing channels (direct, email_sms, paid_ads, organic_search, social, affiliate, referral).

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/sources"
{  "denominator": 0,  "sources": [    {      "source": "string",      "count": 0,      "share": 0    }  ],  "channels": [    {      "channel": "string",      "label": "string",      "count": 0,      "share": 0    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/cockpit

Scope: insights:read.

See website visitors, completed sales and buyer metrics for a 1, 7, 30 or 90 day window, with daily (hourly for 1 day) trends and the previous window of equal length.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

window_days?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/cockpit"
{  "window_days": 0,  "currency_code": "string",  "current_from": "string",  "current_to": "string",  "previous_from": "string",  "checkout_tracking_from": "string",  "current": {    "visits": 0,    "revenue": 0,    "aov": 0,    "new_customers": 0,    "conversion_rate": 0,    "orders": 0,    "repeat_rate": 0,    "active_buyers": 0,    "returning_buyers": 0  },  "previous": {    "visits": 0,    "revenue": 0,    "aov": 0,    "new_customers": 0,    "conversion_rate": 0,    "orders": 0,    "repeat_rate": 0,    "active_buyers": 0,    "returning_buyers": 0  },  "series": [    {      "date": "string",      "current": {        "visits": 0,        "revenue": 0,        "aov": 0,        "new_customers": 0,        "conversion_rate": 0,        "orders": 0,        "repeat_rate": 0,        "active_buyers": 0,        "returning_buyers": 0      },      "previous": {        "visits": 0,        "revenue": 0,        "aov": 0,        "new_customers": 0,        "conversion_rate": 0,        "orders": 0,        "repeat_rate": 0,        "active_buyers": 0,        "returning_buyers": 0      }    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/funnel

Scope: insights:read.

See the Cockpit conversion funnel: people at each step of the brand's saved funnel (or the default funnel) for a 1, 7, 30 or 90 day window, with the previous window for comparison.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

window_days?string|null

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/funnel"
{  "window_days": 0,  "steps": [    {      "id": "string",      "label": "string",      "count": 0,      "previous_count": 0,      "breakdowns": [        {          "id": "string",          "label": "string",          "count": 0,          "previous_count": 0        }      ]    }  ],  "counted_from": "string",  "previous_counted_from": "string",  "orders_in_period": 0,  "prev_orders_in_period": 0,  "purchases": 0,  "prev_purchases": 0,  "order_history_from": "string",  "has_store": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/funnel/definition

Scope: insights:read.

Get the steps of the brand's Cockpit funnel: the saved definition, or the default funnel when none is saved (is_default).

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/funnel/definition"
{  "definition": {    "steps": [      {        "id": "string",        "label": "string",        "events": [          "string"        ],        "breakdowns": [          {            "id": "string",            "label": "string",            "events": [              "string"            ]          }        ]      }    ]  },  "is_default": true,  "has_store": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
DELETE/v1/insights/funnel/definition

Scope: insights:write.

Reset the brand's Cockpit funnel to the default funnel by deleting the saved one. Returns the default for the brand's store status.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/insights/funnel/definition"
{  "definition": {    "steps": [      {        "id": "string",        "label": "string",        "events": [          "string"        ],        "breakdowns": [          {            "id": "string",            "label": "string",            "events": [              "string"            ]          }        ]      }    ]  },  "is_default": true,  "has_store": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
PUT/v1/insights/funnel/definition

Scope: insights:write.

Save the steps of the brand's Cockpit funnel, replacing the saved one. Every event must be one this brand can use (see the event catalog). Returns the stored definition.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/insights/funnel/definition" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "steps": [        {          "id": "string",          "label": "string",          "events": [            "string"          ]        }      ]    }  }'
{  "definition": {    "steps": [      {        "id": "string",        "label": "string",        "events": [          "string"        ],        "breakdowns": [          {            "id": "string",            "label": "string",            "events": [              "string"            ]          }        ]      }    ]  },  "is_default": true,  "has_store": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/insights/funnel/preview

Scope: insights:write.

Count a draft Cockpit funnel without saving it: the same answer as the funnel read, for a 1, 7, 30 or 90 day window. Nothing is stored.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/insights/funnel/preview" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "steps": [        {          "id": "string",          "label": "string",          "events": [            "string"          ]        }      ]    }  }'
{  "window_days": 0,  "steps": [    {      "id": "string",      "label": "string",      "count": 0,      "previous_count": 0,      "breakdowns": [        {          "id": "string",          "label": "string",          "count": 0,          "previous_count": 0        }      ]    }  ],  "counted_from": "string",  "previous_counted_from": "string",  "orders_in_period": 0,  "prev_orders_in_period": 0,  "purchases": 0,  "prev_purchases": 0,  "order_history_from": "string",  "has_store": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/events/samples

Scope: insights:read.

See a few recent occurrences of one event for your brand, with its fields and sample values, so you can tell what the event looks like before building a report on it. Name the event by its id from the events list.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

event*string

The event to sample, by its id from the events list.

limit?integer

How many occurrences to return, 1 to 10. Defaults to 5.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/events/samples?event=string"
{  "event": {    "id": "string",    "label": "string"  },  "window_days": 30,  "samples": [    {      "occurred_at": "string",      "known_customer": true,      "properties": {        "property1": "string",        "property2": "string"      },      "value": 0,      "currency": "string",      "status": "string",      "page": "string",      "page_title": "string",      "referrer": "string",      "landing_page": "string",      "campaign": "string",      "traffic_source": "string",      "traffic_medium": "string",      "items": [        {          "title": "string",          "quantity": 0,          "unit_price": 0        }      ],      "data": {        "property1": null,        "property2": null      },      "payload": {        "property1": null,        "property2": null      }    }  ],  "fields": [    {      "path": "string",      "type": "text",      "example": "string"    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/website/breakdown

Scope: insights:read. MCP tool: get_website_breakdown.

See website traffic from the VYG web pixel for a date range: page views, unique visitors and conversions grouped by page, landing page, traffic source (UTM source, medium, campaign, referrer), event, page variant or a custom event property. Sources are attributed to the session that the event belongs to. Top rows plus an "other" remainder and totals.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/website/breakdown" \  -H "Content-Type: application/json" \  -d '{    "from": "string",    "to": "string",    "group_by": [      "string"    ]  }'
{  "from": "string",  "to": "string",  "group_by": [    "string"  ],  "conversion_events": [    "string"  ],  "rows": [    {      "keys": {        "property1": "string",        "property2": "string"      },      "views": 0,      "visitors": 0,      "events": 0,      "conversions": 0,      "converting_visitors": 0,      "conversion_rate": 0    }  ],  "other": {    "groups": 0,    "views": 0,    "visitors": 0,    "events": 0,    "conversions": 0,    "converting_visitors": 0,    "conversion_rate": 0  },  "totals": {    "views": 0,    "visitors": 0,    "events": 0,    "conversions": 0,    "converting_visitors": 0,    "conversion_rate": 0  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/insights/acquisition

Scope: insights:read.

See where the customers who reached a milestone came from. Milestones are catalog events (custom:, a custom event name, pixel. or web:); customers with any milestone in the range are grouped by their first website touch (falling back to the UTM and referrer of their earliest milestone, then 'direct') by source, channel, referrer host or UTM campaign. Top rows plus other and totals, with per-milestone customer counts.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

from*string

Start of the range, inclusive (ISO 8601, UTC when no offset is given).

to*string

End of the range, exclusive (ISO 8601). At most 366 days after from.

milestones*array<>

Catalog event ids or custom event names: custom:, a custom event name, pixel. or web:. Repeat the query parameter for several milestones.

group_by?string

How to group customers: source (default), channel, referrer_host or utm_campaign.

limit?integer

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/insights/acquisition?from=string&to=string&milestones=string"
{  "range": {    "from": "string",    "to": "string"  },  "group_by": "source",  "milestones": [    {      "id": "string",      "label": "string",      "requested": "string"    }  ],  "rows": [    {      "key": "string",      "label": "string",      "customers": 0,      "milestones": {        "property1": 0,        "property2": 0      }    }  ],  "other": {    "customers": 0,    "milestones": {      "property1": 0,      "property2": 0    }  },  "totals": {    "customers": 0,    "milestones": {      "property1": 0,      "property2": 0    }  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/reports

Scope: insights:read.

List the reports this brand can open, with each report’s category and whether it is ready.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/reports"
{  "reports": [    {      "id": "string",      "name": "string",      "category": "attribution",      "description": "string",      "kind": "builtin",      "status": "ready",      "editable": true,      "controls": [        "date_range"      ],      "window_options": {        "values": [          0        ],        "default": 0      }    }  ]}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/reports

Scope: insights:write.

Save a custom report over one event: its numbers by day, week or month, with optional filters. Returns the saved report.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/reports" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "definition": {      "source": "events",      "event": "string",      "measure": "events",      "breakdown": "day"    }  }'
{  "id": "string",  "name": "string",  "category": "attribution",  "description": "string",  "kind": "builtin",  "status": "ready",  "editable": true,  "controls": [    "date_range"  ],  "window_options": {    "values": [      0    ],    "default": 0  },  "counting_rule": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
GET/v1/reports/{id}

Scope: insights:read.

One report’s name, category, description and how its numbers are counted.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/reports/string"
{  "id": "string",  "name": "string",  "category": "attribution",  "description": "string",  "kind": "builtin",  "status": "ready",  "editable": true,  "controls": [    "date_range"  ],  "window_options": {    "values": [      0    ],    "default": 0  },  "counting_rule": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
PATCH/v1/reports/{id}

Scope: insights:write.

Change a custom report you saved: its name, description, category or definition. Only your own custom reports can be changed.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/reports/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "name": "string",  "category": "attribution",  "description": "string",  "kind": "builtin",  "status": "ready",  "editable": true,  "controls": [    "date_range"  ],  "window_options": {    "values": [      0    ],    "default": 0  },  "counting_rule": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
DELETE/v1/reports/{id}

Scope: insights:write.

Delete a custom report you saved. Only your own custom reports can be deleted.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/reports/string"
{  "deleted": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/reports/{id}/run

Scope: insights:read.

Get a report’s numbers for a date range: columns, rows, totals and how they are counted. The result is kept for up to one hour, and asking again inside that hour returns the saved result.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/reports/string/run" \  -H "Content-Type: application/json" \  -d '{}'
{  "report_id": "string",  "name": "string",  "inputs": {    "from": "string",    "to": "string",    "compare": "none",    "window": 0  },  "columns": [    {      "key": "string",      "label": "string",      "type": "text"    }  ],  "rows": [    {      "property1": "string",      "property2": "string"    }  ],  "row_count": 0,  "truncated": true,  "totals": {    "property1": "string",    "property2": "string"  },  "previous_totals": {    "property1": "string",    "property2": "string"  },  "currency_code": "string",  "counting_rule": "string",  "updated_at": "string",  "cached": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/reports/preview

Scope: insights:read.

Count a draft custom report without saving it: the same numbers a saved report returns, for a date range. The result is kept for up to one hour, and asking again for the same draft and range inside that hour returns the saved result. Nothing is stored in your reports.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/reports/preview" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "source": "events",      "event": "string",      "measure": "events",      "breakdown": "day"    },    "from": "string",    "to": "string"  }'
{  "report_id": "string",  "name": "string",  "inputs": {    "from": "string",    "to": "string",    "compare": "none",    "window": 0  },  "columns": [    {      "key": "string",      "label": "string",      "type": "text"    }  ],  "rows": [    {      "property1": "string",      "property2": "string"    }  ],  "row_count": 0,  "truncated": true,  "totals": {    "property1": "string",    "property2": "string"  },  "previous_totals": {    "property1": "string",    "property2": "string"  },  "currency_code": "string",  "counting_rule": "string",  "updated_at": "string",  "cached": true}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
POST/v1/reports/{id}/duplicate

Scope: insights:write.

Copy a custom report you saved into a new report named " (copy)". Built-in and team reports cannot be duplicated yet.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/reports/string/duplicate"
{  "id": "string",  "name": "string",  "category": "attribution",  "description": "string",  "kind": "builtin",  "status": "ready",  "editable": true,  "controls": [    "date_range"  ],  "window_options": {    "values": [      0    ],    "default": 0  },  "counting_rule": "string"}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}
{  "error": {    "code": "bad_request",    "message": "string"  }}