Skip to content

List users

GET
/users
curl --request GET \
--url 'https://optlo.com/api/v1/users?limit=50&externalIdKind=string' \
--header 'Authorization: Bearer <token>'

Requires users:read.

limit
integer
default: 50 >= 1 <= 100

Maximum number of resources to return on one page.

cursor
string

Opaque cursor from the preceding page. Bound to workspace, resource and filters; survives key rotation.

email
string
/.+@.+/

Case-insensitive exact match; returns all matching users.

externalId
string

Exact external identity, preserving string/number distinction.

externalIdKind
string
default: string
Allowed values: string number

Type of the externalId filter. Numeric and string external IDs are distinct.

Success

Media typeapplication/json
Show child attributesHide child attributes
data
required

Resources on this page.

array of dictionaries
Show child attributesHide child attributes
id
required

Unique identifier for the user.

string
name
required

User’s display name.

nullable string
email
required

User’s email address.

nullable string
externalId
required

User identifier in your system. String and numeric IDs are distinct.

nullable
string
or
number
avatarUrl
required

URL of the user’s avatar image.

nullable string
attrs
required

Custom attributes attached to the user, such as plan or company. Values can be strings, numbers, booleans, or null.

nullable dictionary
Show child attributesHide child attributes
key
additional properties
nullable
string
or
number
or
boolean
createdAt
required

Time the user was created.

string format: date-time
lastVisitedAt
required

Time of the user’s most recent visit. Null if no visit has been recorded.

nullable string format: date-time
nextCursor
required

Pass this cursor to retrieve the next page. Null when no further page is available. When polling events in ascending order, retain the cursor even on empty pages.

nullable string

Example

{
"data": [
{
"id": "user_kR7mP3xB9nQ2vL5z",
"name": "Sam Rivera",
"email": "sam@example.com",
"externalId": "customer_1042",
"avatarUrl": null,
"attrs": {
"plan": "pro",
"company": "Acme"
},
"createdAt": "2026-10-13T09:00:00.000Z",
"lastVisitedAt": "2026-10-13T09:05:00.000Z"
}
],
"nextCursor": null
}