GET
/
v1
/
users
curl https://api.usertour.io/v1/users \
-H 'Authorization: Bearer ak_123456789' \
-H 'Content-Type: application/json'

{
  "results": [
    {
      "id": "usr_123456789",
      "object": "user",
      "attributes": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "role": "admin",
        "department": "engineering",
        "last_login_at": "2024-03-20T08:30:00.000Z"
      },
      "createdAt": "2024-03-20T08:30:00.000Z",
      "companies": null,
      "memberships": null
    },
    {
      "id": "usr_987654321",
      "object": "user",
      "attributes": {
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "role": "user",
        "department": "marketing",
        "last_login_at": "2024-03-19T15:45:00.000Z"
      },
      "createdAt": "2024-03-19T15:45:00.000Z",
      "companies": null,
      "memberships": null
    }
  ],
  "next": "/v1/users?limit=2&cursor=usr_987654321",
  "previous": null
}

​
Query parameters

​
email
string

Filter users by their email address. The search is case-insensitive and must match the exact email value stored in the user’s attributes.

​
segmentId
string

Filter users by segment membership. You can find the segment ID in the Usertour UI by clicking the three-dot menu in the top right corner of the segment page.

​
companyId
string

Filter users by company membership. Only returns users who are members of the specified company.

​
limit
number
default:"20"

Specifies the maximum number of items to return in a single response. The value must be between 1 and 100. If not specified, defaults to 20 items per page.

​
cursor
string

Specifies the starting point for the next page of results. The response will include items that come after (but not including) the object with this ID. To get the next page, use the ID of the last item from your previous request. The easiest way is to use the list object’s cursor field. If not provided, the API will return items from the beginning of the list.

​
expand
string | string[]

See Expanding objects. Available options:

  • memberships: Include basic membership data for each user
  • memberships.company: Include both membership and associated company details
  • companies: Include all companies associated with the user
  • You can request multiple expansions: expand[]=memberships&expand[]=companies

​
Response

Returns a list object containing an array of user objects in the results property. The response includes pagination information in the next and previous fields.

curl https://api.usertour.io/v1/users \
-H 'Authorization: Bearer ak_123456789' \
-H 'Content-Type: application/json'

{
  "results": [
    {
      "id": "usr_123456789",
      "object": "user",
      "attributes": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "role": "admin",
        "department": "engineering",
        "last_login_at": "2024-03-20T08:30:00.000Z"
      },
      "createdAt": "2024-03-20T08:30:00.000Z",
      "companies": null,
      "memberships": null
    },
    {
      "id": "usr_987654321",
      "object": "user",
      "attributes": {
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "role": "user",
        "department": "marketing",
        "last_login_at": "2024-03-19T15:45:00.000Z"
      },
      "createdAt": "2024-03-19T15:45:00.000Z",
      "companies": null,
      "memberships": null
    }
  ],
  "next": "/v1/users?limit=2&cursor=usr_987654321",
  "previous": null
}