Get funnel results Returns results for a funnel in the given date range and with optional filters.
This endpoint returns funnel results for a specific funnel in your project.
You can use the list endpoint to get available funnels and pick the funnel id you want to query.
Examples
Copy the JSON body of any of these examples, and use it in a POST request to https://api.vemetric.com/v1/funnels/{id} (replace {id} with your funnel id) with your API key.
Further down this page, you can find a detailed reference of all the available options you can pass.
Funnel conversion for the last 30 days Funnel conversion for users from the US and Germany Funnel conversion for users from a specific UTM source
Be sure to also check out the filter values endpoint to see which values you can use in the filters field.
Bearer token for a project API key. This endpoint returns data for that project only.
Example: Bearer vem_abcdefghijklmnopqrstuvwxyz123456
Path Parameters
Unique funnel id.
Example: 550e8400-e29b-41d4-a716-446655440000
Request Body (required) application/json object
dateRange
* required
Description
Can be either one of the preset strings below, or an array with two date strings [start, end]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision. Type
"live" | "1hr" | "24hrs" | "7days" | "30days" | "3months" | "6months" | "1year" | array<string, string>
Example
["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]
filters
Description
Optional filters applied before funnel step evaluation.
Show nested properties (12)
type: page
Description
Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts. Example
{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}
Show nested properties (3)
origin
Description
Filter based on the page origin (protocol + host). For example, "https://example.com".
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
path
Description
Filter based on the page path. For example, "/blog".
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
hash
Description
Filter based on the page hash. For example, "#section1".
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: event
Description
Filter by event name and/or event property values. Example
{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}
Show nested properties (2)
name
Description
Filter by event name.
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
properties
Description
Filter by one or more custom event properties.
Show nested properties (3)
property
* required
Description
Event property key inside custom event data. value
* required
Description
Event property value to compare against. operator
* required
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: user
Description
Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior). Example
{"type":"user","anonymous":true}
Show nested properties (1)
anonymous
* required
Description
Filter for anonymous (true) or identified (false) users. type: location
Description
Filter by geographic location fields. Example
{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}
Show nested properties (2)
country
Description
Filter by one or more country codes (ISO-3166 alpha-2, e.g. "US").
Show nested properties (2)
value
* required
Description
List of values to filter by operator
* required
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
city
Description
Filter by one or more city names. Example
{"value":["Berlin","New York"],"operator":"oneOf"}
Show nested properties (2)
value
* required
Description
List of values to filter by operator
* required
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
type: referrer
Description
Filter by referrer name. Example
{"type":"referrer","operator":"eq","value":"Google"}
Show nested properties (2)
value
* required
Description
Referrer value to match. Empty string represents direct/none referrer. operator
* required
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: referrerUrl
Description
Filter by referrer URL. Example
{"type":"referrerUrl","operator":"contains","value":"google.com"}
Show nested properties (2)
value
* required
Description
Referrer URL value to match. Example
"https://google.com"
operator
* required
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: referrerType
Description
Filter by referrer category/type. Example
{"type":"referrerType","operator":"oneOf","value":["search"]}
Show nested properties (2)
value
* required
Description
List of referrer types to match (for example: search, social, email, direct). Example
["search","social"]
operator
* required
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: utmTags
Description
Filter by one or more UTM parameters. Example
{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}
Show nested properties (5)
utmCampaign
Description
Filter by UTM campaign.
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmContent
Description
Filter by UTM content.
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmMedium
Description
Filter by UTM medium.
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmSource
Description
Filter by UTM source.
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmTerm
Description
Filter by UTM term.
Show nested properties (2)
value
* required
Description
Value to filter by operator
* required
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: browser
Description
Filter by browser. Example
{"type":"browser","operator":"oneOf","value":["Chrome"]}
Show nested properties (2)
value
* required
Description
List of browser names to match. Example
["Chrome","Safari"]
operator
* required
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: device
Description
Filter by device type. Example
{"type":"device","operator":"oneOf","value":["desktop"]}
Show nested properties (2)
value
* required
Description
List of device types to match. Example
["desktop","mobile"]
operator
* required
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: os
Description
Filter by operating system. Example
{"type":"os","operator":"oneOf","value":["macOS"]}
Show nested properties (2)
value
* required
Description
List of operating system names to match. Example
["macOS","Windows"]
operator
* required
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: funnel
Description
Filter users based on funnel step completion. Example
{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}
Show nested properties (3)
id
* required
Description
Funnel ID to evaluate for completion status. Example
"550e8400-e29b-41d4-a716-446655440000"
step
* required
Description
Zero-based funnel step index to evaluate. operator
* required
Description
Whether users must have completed or not completed the selected step. Type
"completed" | "notCompleted"
filtersOperator
Description
Operator to apply between multiple filters. Responses 200 Success
application/json period
Description
Resolved query period. from
Description
Resolved UTC start timestamp for the query window. Type
string<pattern:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$>
Example
"2026-01-19T12:30:00Z"
to
Description
Resolved UTC end timestamp for the query window. Type
string<pattern:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$>
Example
"2026-01-19T12:30:00Z"
query
Description
Resolved query configuration used for this response. dateRange
Description
Echo of the incoming dateRange request field. Type
"live" | "1hr" | "24hrs" | "7days" | "30days" | "3months" | "6months" | "1year" | array<string, string>
Example
["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]
filters
Description
Echo of the incoming filters request field.
Show nested properties (12)
type: page
Description
Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts. Example
{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}
Show nested properties (3)
origin
Description
Filter based on the page origin (protocol + host). For example, "https://example.com".
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
path
Description
Filter based on the page path. For example, "/blog".
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
hash
Description
Filter based on the page hash. For example, "#section1".
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: event
Description
Filter by event name and/or event property values. Example
{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}
Show nested properties (2)
name
Description
Filter by event name.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
properties
Description
Filter by one or more custom event properties.
Show nested properties (3)
property
Description
Event property key inside custom event data. value
Description
Event property value to compare against. operator
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: user
Description
Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior). Example
{"type":"user","anonymous":true}
Show nested properties (1)
anonymous
Description
Filter for anonymous (true) or identified (false) users. type: location
Description
Filter by geographic location fields. Example
{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}
Show nested properties (2)
country
Description
Filter by one or more country codes (ISO-3166 alpha-2, e.g. "US").
Show nested properties (2)
value
Description
List of values to filter by operator
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
city
Description
Filter by one or more city names. Example
{"value":["Berlin","New York"],"operator":"oneOf"}
Show nested properties (2)
value
Description
List of values to filter by operator
Description
Operator to apply for the list filter. The "any" operator means that any value is accepted and effectively disables the filter. Type
"any" | "oneOf" | "noneOf"
type: referrer
Description
Filter by referrer name. Example
{"type":"referrer","operator":"eq","value":"Google"}
Show nested properties (2)
value
Description
Referrer value to match. Empty string represents direct/none referrer. operator
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: referrerUrl
Description
Filter by referrer URL. Example
{"type":"referrerUrl","operator":"contains","value":"google.com"}
Show nested properties (2)
value
Description
Referrer URL value to match. Example
"https://google.com"
operator
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: referrerType
Description
Filter by referrer category/type. Example
{"type":"referrerType","operator":"oneOf","value":["search"]}
Show nested properties (2)
value
Description
List of referrer types to match (for example: search, social, email, direct). Example
["search","social"]
operator
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: utmTags
Description
Filter by one or more UTM parameters. Example
{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}
Show nested properties (5)
utmCampaign
Description
Filter by UTM campaign.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmContent
Description
Filter by UTM content.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmMedium
Description
Filter by UTM medium.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmSource
Description
Filter by UTM source.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
utmTerm
Description
Filter by UTM term.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: browser
Description
Filter by browser. Example
{"type":"browser","operator":"oneOf","value":["Chrome"]}
Show nested properties (2)
value
Description
List of browser names to match. Example
["Chrome","Safari"]
operator
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: device
Description
Filter by device type. Example
{"type":"device","operator":"oneOf","value":["desktop"]}
Show nested properties (2)
value
Description
List of device types to match. Example
["desktop","mobile"]
operator
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: os
Description
Filter by operating system. Example
{"type":"os","operator":"oneOf","value":["macOS"]}
Show nested properties (2)
value
Description
List of operating system names to match. Example
["macOS","Windows"]
operator
Description
List matching operator for value. Type
"any" | "oneOf" | "noneOf"
type: funnel
Description
Filter users based on funnel step completion. Example
{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}
Show nested properties (3)
id
Description
Funnel ID to evaluate for completion status. Example
"550e8400-e29b-41d4-a716-446655440000"
step
Description
Zero-based funnel step index to evaluate. operator
Description
Whether users must have completed or not completed the selected step. Type
"completed" | "notCompleted"
filtersOperator
Description
Echo of the incoming filtersOperator request field. funnel
Description
Funnel definition for which these results were computed. id
Description
Unique funnel id. Example
"550e8400-e29b-41d4-a716-446655440000"
icon
Description
Optional funnel icon. steps
Description
Ordered funnel steps.
Show nested properties (3)
id
Description
Unique funnel step id. Example
"zvpslSIPFJQ6oiRCXPMm3"
name
Description
Name of the funnel step. Example
"Visited Landing Page"
filter
Description
Condition that determines when the funnel step is considered completed. Either a pageview or a custom event filter. Example
{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}
Show nested properties (2)
type: page
Description
Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts. Example
{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}
Show nested properties (3)
origin
Description
Filter based on the page origin (protocol + host). For example, "https://example.com".
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
path
Description
Filter based on the page path. For example, "/blog".
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
hash
Description
Filter based on the page hash. For example, "#section1".
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
type: event
Description
Filter by event name and/or event property values. Example
{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}
Show nested properties (2)
name
Description
Filter by event name.
Show nested properties (2)
value
Description
Value to filter by operator
Description
Operator to apply for the string filter. "eq" means equals, "notEq" means not equals. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
properties
Description
Filter by one or more custom event properties.
Show nested properties (3)
property
Description
Event property key inside custom event data. value
Description
Event property value to compare against. operator
Description
String matching operator for value. Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
createdAt
Description
Funnel creation timestamp (ISO 8601). Example
"2026-03-01T10:00:00.000Z"
updatedAt
Description
Funnel last update timestamp (ISO 8601). Example
"2026-03-02T11:30:00.000Z"
results
Description
Funnel results for the given query. activeUsers
Description
Users active in the period and matching filters. steps
Description
Per-step user counts in funnel order.
Show nested properties (4)
id
Description
Unique funnel step id. Example
"zvpslSIPFJQ6oiRCXPMm3"
name
Description
Name of the funnel step. Example
"Visited Landing Page"
users
Description
Users that reached this step. conversionRate
Description
Step-to-step conversion rate in percent. First step is always 100 (or 0 if empty). conversionRate
Description
Conversion rate from first funnel step to last funnel step, in percent. activeUserConversionRate
Description
Conversion rate from active users to last funnel step, in percent. 400 Bad request - invalid request payload or parameters
application/json error
Description
Validation error details. code
Description
Machine-readable validation error code. message
Description
Human-readable validation summary. details
Description
Per-field validation issues.
Show nested properties (2)
field
Description
Path to the invalid request field. message
Description
Validation error message for the field. 401 Unauthorized - invalid or revoked API key
application/json error
Description
Error details. code
Description
Machine-readable error code. message
Description
Human-readable error message. 403 Requested date range is not allowed for the current plan
application/json error
code
Type
"PLAN_LIMIT_EXCEEDED"
404 Funnel was not found
application/json 429 Rate limit exceeded
application/json error
Description
Error details. code
Description
Machine-readable error code. Type
"RATE_LIMIT_EXCEEDED"
message
Description
Human-readable error message. 500 Unexpected internal error
application/json error
Description
Error details. code
Description
Machine-readable error code. Type
"INTERNAL_SERVER_ERROR"
message
Description
Human-readable error message.