List users

Returns a list of users with optional filters, sorting and date range.

Method

POST

Path

/v1/users

The Users Endpoint returns a paginated list of users for your project, with support for date range selection, filtering, and sorting.

It returns anonymous, as well as identified users, and gives you the ability to filter by properties like location, device, or UTM tags.

Examples

Below you can see several examples of how to use the Users Endpoint to retrieve users and order and filter them by different criteria. Further down this page, you can find a detailed reference of all the available options you can pass.

Copy the JSON body of any of these examples, and use it in a POST request to https://api.vemetric.com/v1/users with your API key to see the results.

{
  "dateRange": "7days",
  "filtersOperator": "or",
  "filters": [
    {
      "type": "page",
      "path": {
        "operator": "startsWith",
        "value": "/blog/"
      }
    },
    {
      "type": "event",
      "name": {
        "operator": "eq",
        "value": "Signup"
      }
    }
  ]
}

{
  "filters": [
    {
      "type": "user",
      "anonymous": false
    },
    {
      "type": "location",
      "country": {
        "operator": "oneOf",
        "value": ["US", "DE"]
      }
    }
  ]
}

{
  "orderBy": [
    [
      "lastEventFired",
      "desc",
      {
        "name": {
          "operator": "eq",
          "value": "Signup"
        },
        "properties": [
          {
            "property": "provider",
            "operator": "eq",
            "value": "google"
          }
        ]
      }
    ]
  ]
}

{
  "dateRange": ["2026-01-01", "2026-01-31"],
  "filters": [
    {
      "type": "user",
      "anonymous": true
    },
    {
      "type": "device",
      "operator": "oneOf",
      "value": ["mobile"]
    },
    {
      "type": "utmTags",
      "utmSource": {
        "operator": "eq",
        "value": "google"
      }
    }
  ]
}

{
  "dateRange": "30days",
  "limit": 100,
  "offset": 100
}

Be sure to also check out the filter values endpoint to see which values you can use in the filters field.

Headers

Authorization

required

Bearer token for a project API key. This endpoint returns data for that project only.

Example: Bearer vem_abcdefghijklmnopqrstuvwxyz123456

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 to restrict the user list.
Type
array<object>
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.
Type
object
Default
"page"
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".
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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".
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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".
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
object
Default
"event"
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.
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
array<object>
Show nested properties (3)

property

* required
Description
Event property key inside custom event data.
Type
string
Example
"provider"

value

* required
Description
Event property value to compare against.
Type
string
Example
"github"

operator

* required
Description
String matching operator for value.
Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"eq"

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).
Type
object
Default
"user"
Example
{"type":"user","anonymous":true}
Show nested properties (1)

anonymous

* required
Description
Filter for anonymous (true) or identified (false) users.
Type
boolean
Example
true

type: location

Description
Filter by geographic location fields.
Type
object
Default
"location"
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").
Type
object
Show nested properties (2)

value

* required
Description
List of values to filter by
Type
array<string>

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.
Type
object
Example
{"value":["Berlin","New York"],"operator":"oneOf"}
Show nested properties (2)

value

* required
Description
List of values to filter by
Type
array<string>

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.
Type
object
Default
"referrer"
Example
{"type":"referrer","operator":"eq","value":"Google"}
Show nested properties (2)

value

* required
Description
Referrer value to match. Empty string represents direct/none referrer.
Type
string
Example
"Google"

operator

* required
Description
String matching operator for value.
Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"eq"

type: referrerUrl

Description
Filter by referrer URL.
Type
object
Default
"referrerUrl"
Example
{"type":"referrerUrl","operator":"contains","value":"google.com"}
Show nested properties (2)

value

* required
Description
Referrer URL value to match.
Type
string
Example
"https://google.com"

operator

* required
Description
String matching operator for value.
Type
"any" | "eq" | "notEq" | "contains" | "notContains" | "startsWith" | "endsWith"
Example
"contains"

type: referrerType

Description
Filter by referrer category/type.
Type
object
Default
"referrerType"
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).
Type
array<string>
Example
["search","social"]

operator

* required
Description
List matching operator for value.
Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"

type: utmTags

Description
Filter by one or more UTM parameters.
Type
object
Default
"utmTags"
Example
{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}
Show nested properties (5)

utmCampaign

Description
Filter by UTM campaign.
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
object
Show nested properties (2)

value

* required
Description
Value to filter by
Type
string

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.
Type
object
Default
"browser"
Example
{"type":"browser","operator":"oneOf","value":["Chrome"]}
Show nested properties (2)

value

* required
Description
List of browser names to match.
Type
array<string>
Example
["Chrome","Safari"]

operator

* required
Description
List matching operator for value.
Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"

type: device

Description
Filter by device type.
Type
object
Default
"device"
Example
{"type":"device","operator":"oneOf","value":["desktop"]}
Show nested properties (2)

value

* required
Description
List of device types to match.
Type
array<string>
Example
["desktop","mobile"]

operator

* required
Description
List matching operator for value.
Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"

type: os

Description
Filter by operating system.
Type
object
Default
"os"
Example
{"type":"os","operator":"oneOf","value":["macOS"]}
Show nested properties (2)

value

* required
Description
List of operating system names to match.
Type
array<string>
Example
["macOS","Windows"]

operator

* required
Description
List matching operator for value.
Type
"any" | "oneOf" | "noneOf"
Example
"oneOf"

type: funnel

Description
Filter users based on funnel step completion.
Type
object
Default
"funnel"
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.
Type
string
Example
"550e8400-e29b-41d4-a716-446655440000"

step

* required
Description
Zero-based funnel step index to evaluate.
Type
integer
Example
1

operator

* required
Description
Whether users must have completed or not completed the selected step.
Type
"completed" | "notCompleted"
Example
"completed"

filtersOperator

Description
Operator to apply between multiple filters.
Type
"and" | "or"
Default
"and"

orderBy

Description
Gives you the ability to order users by a specific field and direction. At the moment it's only possible to order by one field.
Type
array<array<"lastSeenAt" | "displayName" | "identifier" | "country", "asc" | "desc"> | array<"lastEventFired", "asc" | "desc", object>>
Default
[["lastSeenAt","desc"]]
Example
[["lastEventFired","desc",{"name":{"operator":"eq","value":"Signup"},"properties":[{"property":"provider","operator":"eq","value":"google"}]}]]

limit

Description
Limits the number of returned users. Max value is 1000.
Type
integer
Default
100

offset

Description
Number of users to skip from the start of the result set.
Type
integer
Default
0

Responses

200 Success
application/json

period

Description
Resolved query period.
Type
object

from

Description
Resolved UTC start timestamp for the user list 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 user list 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"

pagination

Description
Pagination metadata.
Type
object

limit

Description
Applied row limit.
Type
integer

offset

Description
Applied row offset.
Type
integer

returned

Description
Number of user rows returned in users.
Type
integer

users

Description
List of user rows for the current page.
Type
array<object>

id

Description
Vemetric's internal user ID.
Type
string
Example
"123"

identifier

Description
User identifier if available (the value you provided to identify the user).
Type
string | null
Example
"[email protected]"

displayName

Description
User display name if available.
Type
string | null
Example
"John Doe"

country

Description
ISO-3166 alpha-2 country code, or null when unknown.
Type
string | null
Example
"US"

city

Description
User city, or null when unknown.
Type
string | null
Example
"Berlin"

lastSeenAt

Description
UTC timestamp of the latest activity for this user within the selected period.
Type
string<pattern:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$> | null
Example
"2026-01-19T12:30:00Z"

lastEventFiredAt

Description
UTC timestamp of when the user last fired the event referenced by orderBy[0][2]. Populated only for orderBy[0][0] = "lastEventFired", otherwise null.
Type
string<pattern:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$> | null
Example
"2026-01-19T12:30:00Z"

avatarUrl

Description
Avatar URL if available.
Type
string | null
Example
"https://cdn.example.com/avatar.png"

data

Description
Data attributes collected for this user.
Type
object
Example
{"plan":"pro","company":"Vemetric"}

anonymous

Description
Whether the user is anonymous (not identified).
Type
boolean
Example
false
400 Bad request - invalid request payload or parameters
application/json

error

Description
Validation error details.
Type
object

code

Description
Machine-readable validation error code.
Type
"VALIDATION_ERROR"

message

Description
Human-readable validation summary.
Type
string

details

Description
Per-field validation issues.
Type
array<object>
Show nested properties (2)

field

Description
Path to the invalid request field.
Type
string
Example
"groupBy.0"

message

Description
Validation error message for the field.
Type
string
401 Unauthorized - invalid or revoked API key
application/json

error

Description
Error details.
Type
object

code

Description
Machine-readable error code.
Type
"UNAUTHORIZED"

message

Description
Human-readable error message.
Type
string
403 Requested date range is not allowed for the current plan
application/json

error

Description
Type
object

code

Description
Type
"PLAN_LIMIT_EXCEEDED"

message

Description
Type
string
429 Rate limit exceeded
application/json

error

Description
Error details.
Type
object

code

Description
Machine-readable error code.
Type
"RATE_LIMIT_EXCEEDED"

message

Description
Human-readable error message.
Type
string
500 Unexpected internal error
application/json

error

Description
Error details.
Type
object

code

Description
Machine-readable error code.
Type
"INTERNAL_SERVER_ERROR"

message

Description
Human-readable error message.
Type
string

Ready to understand your users?

Start tracking
Pricing About Documentation Customers Changelog Blog
300 stars