Docs·Goals
GET
/api/v1/event/analytics/goals/metricsGet goal results
Every goal of the audience, oldest first, with how it converted in the date range: people converted, total completions, revenue, revenue per conversion and conversion rate. Goals with no conversions are included with zeros.
Conversions are counted per person: an identified visitor counts once across all their devices, an anonymous one once per browser. Revenue is the payment amount carried by the matching events themselves, net of refunds, so a goal that matches page views or events without an amount earns 0.
Keys: an account key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
contactListId | query | string | The id of the audience (the tracked site) to read, a UUID: anything else returns a 400. You must be a member of the workspace the audience belongs to, or the call returns a 401. An id that matches no audience is not an error: the call returns no data. |
startDate | query | string | Start of the date range, read as UTC: a date such as 2026-09-01 (from midnight), or an exact time such as 2026-09-01T09:30:00Z. Use one of these two forms. |
endDate | query | string | End of the date range, read as UTC. A date such as 2026-09-30 includes that whole day; an exact time such as 2026-09-30T18:00:00Z ends the range right before that moment. If the workspace has gone past its plan's event allowance this billing period, the range is cut short at the moment the allowance ran out. |
segmentId? | query | string | Leave this out. It does not take the id of a segment from the Segments page: such an id matches no one, so the results come back empty. To narrow the results to a segment, add ["cohort_id",["<segment id>"]] to filter. |
filter? | query | string | Narrows the results: a URL-encoded JSON array of conditions, each [key, values, operator], where a missing operator means is. Example: [["country",["US","GB"]],["page",["/pricing"],"startsWith"]] keeps visits from the US or the UK that viewed a page starting with /pricing. Every condition must match, and each key can appear once (a second condition on the same key replaces the first). A condition matches any of its values, except that isNot, notContains and notRegex rule out all of them. Operators: is and isNot (exact), contains, notContains, startsWith and endsWith (ignoring case), regex and notRegex (RE2 syntax, so no lookarounds; a pattern that does not compile returns a 400), and isNull and isNotNull (the value is not set, or is set; send [] as the values). Keys: channel, referrer_source, referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content, country (a two-letter code), region, city, browser, browser_version, os, os_version, screen_size (Desktop, Mobile or Tablet), hostname, entry_page, exit_page, page and event_name (visits that viewed such a page or sent such an event), identified (["true"] or ["false"]), goal_id (people who completed the goal in the range) and cohort_id (members of a segment). The last two take ids and only is or isNot. Unknown keys, and a filter that is not valid JSON, are ignored rather than refused. |
Response
An array of GoalMetricsItem.
| Prop | Type | Notes |
|---|---|---|
conversionRate | number | conversions divided by the people and anonymous visitors with any activity in the range: a fraction from 0 to 1 with four decimals. |
aov | number | Average revenue per conversion: revenue divided by conversions, two decimals. |
revenue | number | Net payment amount carried by the matching events, in the audience's reporting currency (Settings → Revenue), two decimals. |
totalConversions | number | Every completion, so one person completing twice counts twice. |
conversions | number | People (or anonymous visitors) who completed the goal in the range, each counted once. |
matchType | string | The goal type: pageview, event or scroll (Pageview, Custom event or Scroll depth in the app). |
name | string | The goal's name. |
id | string | The goal id. |
Request
curl 'https://app.spreelytics.com/api/v1/event/analytics/goals/metrics?contactListId=…&startDate=…&endDate=…' \
-H 'Authorization: Bearer YOUR_API_KEY'
const url = new URL('https://app.spreelytics.com/api/v1/event/analytics/goals/metrics');
url.searchParams.set('contactListId', '…');
url.searchParams.set('startDate', '…');
url.searchParams.set('endDate', '…');
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/event/analytics/goals/metrics",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"contactListId": "…", "startDate": "…", "endDate": "…"},
)
data = res.json()
Response
[
{
"conversionRate": 0,
"aov": 0,
"revenue": 0,
"totalConversions": 0,
"conversions": 0,
"matchType": "string",
"name": "string",
"id": "string"
}
]