Get Users with Filters

This endpoint searches and retrieves platform users based on specified filter criteria, returning only the requested fields for each matching user. It provides flexible filtering capabilities with pagination support for large result sets.

Authorization

Bearer token Required

Found in the platform under community settings > API keys.
Permission: Get User Data

Available Fields

All user fields (including custom fields) can be requested in the response.

Example platform fields:

Platform field	Field name
Email	email
First Name	first_name
Last Name	last_name
Join date	join_date
Total XP	xp
Total Coins	coins

Field names in the request must match the database column names shown in the user fields table.

All user fields (including custom fields) can be filtered.
The filter parameter supports three types of filtering operations:

1. Exact Match

Filter users by exact field value.

2. Comparison Operators

Use operators for numeric and date field comparisons:
Supported operators:

gte - Greater than or equal to

lte - Less than or equal to

gt - Greater than

lt - Less than

3. Range Queries

Combine operators to filter within a range.

Pagination

Results are paginated with a fixed page size of 200 records per response.
The API supports two pagination methods:

Cursor-Based Pagination (Recommended)

Use for sequential retrieval of all pages:

Response includes next_cursor when more results exist.

Send cursor parameter in subsequent requests to get the other pages.

Page-Based Pagination

Use to get to a specific page:

Response includes total_pages and current_page.

Send page with the number in subsequent requests to get the specific page.

Important: Do not send both cursor and page parameters in the same request. Choose one pagination method per request sequence.

Request

Body Params application/json

Example

{
    "fields": [
        "email",
        "join_date",
        "first_name",
        "last_name"
    ],
    "filter": {
        "join_date": {
            "lte": "2025-08-28",
            "gte": "2025-01-01"
        },
        "first_name": "Annie"
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success - without pagination

application/json

Body

Example

{
    "status": "success",
    "data": {
        "pagination": {
            "total": 14,
            "currentPage": 1,
            "totalPages": 1,
            "hasNextPage": false,
            "hasPrevPage": false
        },
        "data": [
            {
                "email": "Test@gmail.com",
                "join_date": "2025-03-03T03:24:54.828Z",
                "first_name": "Test",
                "last_name": "Lee"
            },
            ...
            {
                "email": "coffeeplanetklee@outlook.com",
                "join_date": "2025-02-13T04:44:56.067Z",
                "first_name": "Klee",
                "last_name": "Planet"
            }
        ]
    }
}

🟢200Success - with pagination

🟠401Invalid token

🟠401Insufficient permission

Authorization#

Available Fields#

Filter Options#

1. Exact Match#

2. Comparison Operators#

3. Range Queries#

Pagination#

Cursor-Based Pagination (Recommended)#

Page-Based Pagination#