--- title: "POST /v1/users | Documentation - Vemetric" description: "List users" url: https://vemetric.com/docs/api/endpoints/post-v1-users --- # 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](https://vemetric.com/docs/product-analytics/user-identification), 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](#request-body) 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. ```json { "dateRange": "7days", "filtersOperator": "or", "filters": [ { "type": "page", "path": { "operator": "startsWith", "value": "/blog/" } }, { "type": "event", "name": { "operator": "eq", "value": "Signup" } } ] } ``` ```json { "filters": [ { "type": "user", "anonymous": false }, { "type": "location", "country": { "operator": "oneOf", "value": ["US", "DE"] } } ] } ``` ```json { "orderBy": [ [ "lastEventFired", "desc", { "name": { "operator": "eq", "value": "Signup" }, "properties": [ { "property": "provider", "operator": "eq", "value": "google" } ] } ] ] } ``` ```json { "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" } } ] } ``` ```json { "dateRange": "30days", "limit": 100, "offset": 100 } ``` Be sure to also check out the [filter values endpoint](https://vemetric.com/docs/api/endpoints/post-v1-filters-values) to see which values you can use in the `filters` field. ## Headers Authorization required Project API key (starts with `vem_`), created in the project settings on the API tab. Requests only return data of that key's project. Example: `Bearer vem_xxxxxxxxxxxx` ## 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 Example \["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"\] * * * `filters` Description Optional filters to restrict the user list. Type array 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 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 * * * `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 * * * `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 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 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 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 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<"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 Example "2026-01-19T12:30:00Z" * * * `to` Description Resolved UTC end timestamp for the user list query window. Type string 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 `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 "john@example.com" * * * `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 | 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 | 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 Error details. Type object `code` Description Machine-readable error code. `HTTP_ERROR` is returned for a malformed JSON body. Type "VALIDATION\_ERROR" | "HTTP\_ERROR" * * * `message` Description Human-readable error message. Type string * * * `details` Description Per-field validation issues. Only present for `VALIDATION_ERROR`. Type array 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 - missing, malformed, 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 Error details. Type object `code` Description Machine-readable error code. Type "PLAN\_LIMIT\_EXCEEDED" * * * `message` Description Human-readable error message. Type string * * * * * * 429 Rate limit exceeded - retry after the number of seconds in the Retry-After header 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\_ERROR" * * * `message` Description Human-readable error message. Type string * * * * * *