Run a chart

Runs a chart definition and returns the numbers, without saving anything. This is the engine behind the report builder, and the call to make when the web analytics endpoints do not give you a number directly. It is a read sent as a POST because a definition does not fit in a URL, so every role can call it, Viewer included.

A definition has a chart type, a window (range, or startDate and endDate) cut into buckets of one interval, and one or more series. Each series measures one event, or a group of events, with a metric, and can carry its own filters. globalFilters apply to every series, and breakdowns split every series by one or more properties.

{
  "chartType": "line",
  "interval": "day",
  "range": "30d",
  "series": [
    { "id": "a", "event": "page_view", "metric": "unique" },
    { "id": "b", "event": "signup", "filters": [{ "name": "plan", "operator": "is", "value": ["pro"] }] }
  ],
  "breakdowns": ["country"],
  "globalFilters": [{ "name": "channel", "operator": "is", "value": ["Organic Search"] }]
}

That asks, day by day over the last 30 days and split by country, how many people viewed a page and how many signup events had plan set to pro, counting only visits from organic search.

A series has an id (any string, returned on the result) and an event: page_view, a custom event name or another tracked type such as scroll, as listed by GET /meta/events. The rest is optional:

• metric: count (every event, the default), unique (distinct people), session (distinct sessions), user_average (events per person), one_event_per_user (each person's latest matching event only), property_sum, property_average, property_max or property_min (arithmetic over the numeric values of property; values that are not numbers are skipped), sum (revenue in your reporting currency, net of refunds) or average (the average payment).
• events: two or more event names counted as one metric, such as ["signup", "login"], with the first one also in event. Under unique, a person who did both counts once.
• type: event (the default), profile (the people seen in each bucket, whatever they did) or cohort (the members of the segment in cohortId seen in each bucket). Send an empty event with these two.
• displayName: the name the series comes back under.
• filters: conditions for this series only, shaped like globalFilters.

A filter is { "name", "operator", "value" } and nothing else. name is a property: a standard one such as path, country, browser or utm_source (the catalog from GET /meta/events lists them all), profile.email and the like for a person attribute, a custom event property key, or cohort for segment membership. Custom names may only use letters, digits, _, . and -, up to 128 characters. value is always an array of strings, and a row with an empty array is skipped unless its operator takes no value. The operators:

• is, isNot: an exact match with any of the values. isNot on a custom property also matches events without it.
• contains, doesNotContain, startsWith, endsWith: text matches that ignore case.
• regex: a regular expression in RE2 syntax.
• isNull, isNotNull: missing or empty, and present. Send [] as the value.
• gt, gte, lt, lte: numeric comparisons. Only the first value is used.
• inCohort, notInCohort: only with "name": "cohort", and the values are segment ids.

Chart types. line, area, bar, pie and metric all return the same time series; the type only tells your own code how to draw it. Four types compute something else, and profile and segment series are ignored by them:

• funnel: the series are the steps, 2 to 8 of them, in order. The answer is in funnel.
• conversion: the first series starts the clock and the second is the conversion. The answer is one series of percentages per bucket, plus the totals in conversion.
• retention: the first series puts a person in a period, and the second counts as coming back (the first again when there is no second). The answer is in retention.
• sankey: each series, up to 4, is a starting event, and the answer is the paths around it, in sankey and sankeyFlows.

Limits. At most 20 series, not counting event series with an empty event, which are dropped. A series holds at most 1,000 buckets, and a longer window is cut off at the 1,000th, so pick a coarser interval for long ranges. An unknown field anywhere in the body answers 400, which is why a saved report's config cannot be sent here: run it with GET /reports/{reportId}/chart. When the workspace is past its plan's allowance, the window ends where the allowance ran out (see dataCutoff on GET /billing/usage).

Keys: an account key or an audience key. Getting started explains both kinds.

Parameters

Request body

Response

curl -X POST 'https://app.spreelytics.com/api/v1/spreelytics/chart?contactListId=…' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ … }'

const res = await fetch('https://app.spreelytics.com/api/v1/spreelytics/chart', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ /* see Request body above */ }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://app.spreelytics.com/api/v1/spreelytics/chart",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={},  # see Request body above
)
data = res.json()

{
  "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"
    }
  ]
}