Users

Search users

Search users in a project. Filter by attributes (user id, email, country, etc.), optionally narrow by free-text query, and paginate results.

Method

POST

URL

/public/:projectKey/users

Parameters

Name	Type	Description
projectKey	string	The project key (required)
q	string	Optional free-text query (URL query param). When both `q` and `query` (body) are provided, `q` overrides.

Payload

Name	Type	Description
filters	array	Filter list (optional)
query	string	Free-text query against user id / email / name (max 100)
startTimestamp	epoch (ms)	Start of time window (optional, min 946684800000)
endTimestamp	epoch (ms)	End of time window (optional, > startTimestamp)
limit	integer	Page size, 1-200 (optional, default: 50)
page	integer	Page number, starts at 1 (optional, default: 1)
sortBy	string	User column to sort by (optional)
sortOrder	string	`asc` or `desc` (optional)
columns	array	Additional user columns to include in the response

Request Headers

Authorization: Bearer {YOUR_ORGANIZATION_API_KEY}

Example Request

curl -X POST \
  {BASE_URL}/public/3sWXSsqHgSKnE87YkNJK/users \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer {YOUR_ORGANIZATION_API_KEY}' \
  --data-raw '{
    "query": "mickael",
    "limit": 50,
    "page":  1,
    "sortOrder": "desc"
  }'

Example Response

{
  "data": {
    "total": 1,
    "users": [
      {
        "$user_id": "mickael@openreplay.com",
        "$email": "mickael@openreplay.com",
        "$name": "Mickael",
        "$first_name": "Mickael",
        "$last_name": "",
        "$created_at": 1623440822825,
        "$last_seen": 1623689478617
      }
    ]
  }
}

Get user

Get identity attributes and high-level stats for a particular user.

Method

GET

URL

/public/:projectKey/users/:userId

Parameters

Name	Type	Description
projectKey	string	The project key (required)
userId	string	The ID set via `tracker.setUserID` (required, max 256)

Request Headers

Authorization: Bearer {YOUR_ORGANIZATION_API_KEY}

Status Codes

200: Response sent as JSON in body
400: Invalid userId (empty or > 256 chars)
404: User not found

Example Request

curl -X GET \
  {BASE_URL}/public/3sWXSsqHgSKnE87YkNJK/users/mickael@openreplay.com \
  -H 'Authorization: Bearer {YOUR_ORGANIZATION_API_KEY}'

Example Response

{
  "data": {
    "$user_id": "mickael@openreplay.com",
    "$email": "mickael@openreplay.com",
    "$name": "Mickael",
    "$first_name": "Mickael",
    "$last_name": "",
    "$phone": "",
    "$avatar": "",
    "$created_at": 1623440822825,
    "distinct_ids": ["15bd70f6-aedf-4544-8ae6-57eb66398e94"],
    "$country": "FR",
    "$state": "",
    "$city": "",
    "$first_event_at": 1623440822825,
    "$last_seen": 1623689478617
  }
}

Delete user

Delete a user and all associated data. Schedules a background job; the response contains the jobId you can poll via the Jobs API.

Method

DELETE

URL

/public/:projectKey/users/:userId

Parameters

Name	Type	Description
projectKey	string	The project key (required)
userId	string	The ID set via `tracker.setUserID` (required, max 256)

Request Headers

Authorization: Bearer {YOUR_ORGANIZATION_API_KEY}

Status Codes

200: Job scheduled, returned in body
400: Invalid userId (empty or > 256 chars)
409: A deletion job for this user is already scheduled or running

Example Request

curl -X DELETE \
  {BASE_URL}/public/3sWXSsqHgSKnE87YkNJK/users/mickael@example.com \
  -H 'Authorization: Bearer {YOUR_ORGANIZATION_API_KEY}'

Example Response

{
  "data": {
    "jobId": 22345,
    "description": "Delete user sessions of userId = mickael@example.com",
    "status": "scheduled",
    "projectId": 1,
    "action": "delete_user_data",
    "referenceId": "mickael@example.com",
    "createdAt": 1623912962910,
    "updatedAt": null,
    "startAt": 1623954600000,
    "errors": null
  }
}

Change the replay-file delete time ?

The deletion job is a 2 step process: First, sessions and their cascading events get deleted from the database overnight. Second, replay files are scheduled to expire (in 30 days) in the object storage.

If you’re using minio (vanilla installation), and you wish to change the default expiry/lifecycle policy, follow the below instructions:

In your server, run openreplay -e
Under the chalice section, define a new env variable called SCH_DELETE_DAYS with a value equal to the number of days you want to keep the replay file before delete (greater or equal to 0)
Save and quit using :wq
Run k9s -n db
Use the keyboard arrows to navigate the list and get to the minio-* container
Press s to have shell access the Minio (object storage) container
Run mc alias set minio http://localhost:9000 $MINIO_ACCESS_KEY $MINIO_SECRET_KEY
To delete replay files 14 days after the delete-job execution

export EXPIRATION_DAYS=14
mc ilm add --expiry-days $EXPIRATION_DAYS --tags "to_delete_in_days=${EXPIRATION_DAYS}" minio/mobs

Use exit to exit the Minio container
Run :quit to exit the Kubernetes CLI