--- title: "POST /v1/users/events | Documentation - Vemetric" description: "List user events" url: https://vemetric.com/docs/api/endpoints/post-v1-users-events --- # List user events Returns events for one user within a specified date range and with optional filters. * * * Method POST Path /v1/users/events This endpoint returns events for a single user within a selected date range. Provide either `id` or `identifier` as query parameter to select the user, and use the request body to define date range, optional filters, and pagination. ## Examples Below you can see several examples of how to use this endpoint to retrieve events from a single user. 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/events?id=123` (or `?identifier=your-user-id`) with your API key. ```json { "dateRange": "30days" } ``` ```json { "dateRange": ["2026-01-01", "2026-01-31"], "filters": [ { "type": "event", "name": { "operator": "eq", "value": "DownloadImage" } } ] } ``` ```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` ## Query Parameters id string optional Vemetric's internal user ID. You have to either provide `id` or `identifier`. Example: `123` identifier string optional User identifier value. You have to either provide `identifier` or `id`. Example: `your-user-id` ## 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 returned events. Type array Show nested properties (5) `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: 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: 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" * * * * * * * * * `filtersOperator` Description Operator to apply between multiple filters. Type "and" | "or" Default "and" * * * `limit` Description Limits the number of returned events. Max value is 1000. Type integer Default 100 * * * `offset` Description Number of events 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 events query window. Type string Example "2026-01-19T12:30:00Z" * * * `to` Description Resolved UTC end timestamp for the events 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 event rows returned in `events`. Type integer * * * * * * `events` Description List of user events for the requested page. Type array `sessionId` Description Session id of the event. Type string * * * `name` Description Event name. Type string * * * `isPageView` Description Whether this event is a pageview. Type boolean * * * `createdAt` Description UTC timestamp when the event was created. Type string Example "2026-01-19T12:30:00Z" * * * `origin` Description URL origin if available (for pageviews). Type string | null * * * `path` Description URL path if available (for pageviews). Type string | null * * * `hash` Description URL hash if available (for pageviews). Type string | null * * * `data` Description Event data key-value map. Type object Example {"plan":"pro"} * * * * * * 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 * * * * * * 404 User was not found application/json `error` Description Error details. Type object `code` Description Machine-readable error code. Type "USER\_NOT\_FOUND" * * * `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 * * * * * *