Docs·Reports
GET
/api/v1/spreelytics/reports/:reportId/chartRun a saved report
Runs a saved report and returns its chart data, in the same shape as POST /chart. You send only the id: the server reads the saved config, turns the builder's settings into a chart request and runs it in the audience's reporting timezone.
What to expect from that conversion:
- The saved
rangeandintervalare used, unless you send bothstartDateandendDate, which replace the window. The interval stays the saved one. - A
mapcard runs as a breakdown by country, and ahistogramcard asbar. - Formula series are not computed. Work them out from the other series, as the app does.
- A saved funnel or conversion with no window gets 7 days. The saved
limitis not applied, so every breakdown value comes back. - A card of kind
breakdownormetricshas no series, so its result is empty. The app draws those cards from the web analytics endpoints.
It answers 404 when the id is not a report in this audience. Every role can call it, Viewer included.
Keys: an account key or an audience key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
reportId | path | string | The report id. |
contactListId | query | string | The audience id, a UUID. With an audience key it must be that key's own audience. |
startDate? | query | string | Optional, together with endDate: run over this window instead of the saved one. YYYY-MM-DD means the start of that day in the audience's timezone, and a full timestamp is used as given. Sending only one of the two does nothing. |
endDate? | query | string | Optional, together with startDate. A bare YYYY-MM-DD includes that whole day, and a timestamp is an exclusive end. An end before the start answers 400. |
Response
| Prop | Type | Notes |
|---|---|---|
series | SpreelyticsChartSeries[] | The time series, biggest first by window total: one per series, or one per series and breakdown value. Each has id, name, data and metrics. data holds one { date, value } per bucket, date being the bucket start as an ISO timestamp, plus previous when you asked for a comparison. name is the series' displayName, or a name made from its event; with a breakdown it is the value ((none) when empty) and id is the series id, a colon and that value. In a series' metrics, sum is the value over the whole window, so a person seen on three days counts once for unique, while average, min and max are over the buckets and count is the number of buckets. Empty for funnel, retention and sankey. |
metrics | SpreelyticsSeriesMetrics | Totals across the series: sum adds up their sum values, average spreads that over the buckets, max is the largest bucket of any series, min is always 0 and count is how many series came back. For funnel, conversion, retention and sankey, read that chart's own field instead. |
funnel | SpreelyticsFunnelData | Funnel only. steps holds each step's name, visitors (people who reached at least that step, in order, within the window) and dropOffRate (the share lost since the step before, 0 to 1, always 0 on the first). completionRate is the last step over the first, 0 to 1. |
retention | SpreelyticsRetentionRow[] | Retention only. One row per period in which people first did the entry event: cohort (that period), size (how many people) and values, the share of them who came back in each period from their own one (index 0) onwards, 0 to 1. A period that has not happened yet is null, which is not the same as nobody coming back. |
retentionIdentifiedOnly | boolean | Retention only. Present and true when the audience tracks cookielessly, or switched that setting before. Anonymous ids change every day under cookieless tracking, so for that stretch only identified people are counted. |
conversion | SpreelyticsConversionTotals | Conversion only. Totals over the whole window: entered (people who did the first event), converted (how many of them did the second within funnelWindowSeconds) and rate, which is converted over entered as a percentage, 0 to 100. |
sankey | SpreelyticsSankeyData | Sankey only. The first starting event's flow: nodes (each { name }; the same event at two depths is two nodes) and links (source and target are positions in nodes, value is how many people took that step). |
sankeyFlows | SpreelyticsSankeyFlow[] | Sankey only. One flow per starting event, up to 4, each with its series id, the anchor it starts from and its own nodes and links. |
Request
curl 'https://app.spreelytics.com/api/v1/spreelytics/reports/:reportId/chart?contactListId=…' \
-H 'Authorization: Bearer YOUR_API_KEY'
const url = new URL('https://app.spreelytics.com/api/v1/spreelytics/reports/:reportId/chart');
url.searchParams.set('contactListId', '…');
const res = await fetch(url, {
headers: { Authorization: 'Bearer YOUR_API_KEY' },
});
const data = await res.json();
import requests
res = requests.get(
"https://app.spreelytics.com/api/v1/spreelytics/reports/:reportId/chart",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"contactListId": "…"},
)
data = res.json()
Response
{
"series": [
{
"id": "string",
"name": "string",
"metrics": {
"sum": 0,
"average": 0,
"min": 0,
"max": 0,
"count": 0,
"previous": 0
},
"data": [
{
"date": null,
"value": null,
"previous": null
}
]
}
],
"metrics": {
"sum": 0,
"average": 0,
"min": 0,
"max": 0,
"count": 0,
"previous": 0
},
"funnel": {
"steps": [
{
"name": "string",
"visitors": 0,
"dropOffRate": 0
}
],
"completionRate": 0
},
"retention": [
{
"cohort": "string",
"size": 0,
"values": [
0
]
}
],
"retentionIdentifiedOnly": true,
"conversion": {
"entered": 0,
"converted": 0,
"rate": 0
},
"sankey": {
"nodes": [
{
"name": "string"
}
],
"links": [
{
"source": 0,
"target": 0,
"value": 0
}
]
},
"sankeyFlows": [
{
"nodes": [
{
"name": null
}
],
"links": [
{
"source": null,
"target": null,
"value": null
}
],
"id": "string",
"anchor": "string"
}
]
}