Skip to main content
POST
/
engage
Query Profiles
curl --request POST \
  --url https://{regionAndDomain}.com/api/query/engage \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'distinct_id=<string>' \
  --data 'distinct_ids=<string>' \
  --data 'data_group_id=<string>' \
  --data 'where=<string>' \
  --data 'output_properties=<string>' \
  --data 'session_id=<string>' \
  --data page=123 \
  --data behaviors=123 \
  --data as_of_timestamp=123 \
  --data 'filter_by_cohort=<string>' \
  --data include_all_users=true
{
  "page": 0,
  "page_size": 1000,
  "results": [
    {
      "$distinct_id": 4,
      "$properties": {
        "$created": "2008-12-12T11:20:47",
        "$email": "example@mixpanel.com",
        "$first_name": "Example",
        "$last_name": "Name",
        "$last_seen": "2008-06-09T23:08:40"
      }
    }
  ],
  "session_id": "1234567890-EXAMPL",
  "status": "ok",
  "total": 1
}
Query user (or group) profile data and return list of users (or groups) that fit specified parameters. API responses will return at most page_size records for each request. To request additional records, callers should repeat their call to the API using the same where param, but provide a session_id parameter with a value taken from the first response, and include a page parameter with a value one greater than the value of page in the response. A caller trying to retrieve all of the records for a particular query might use an algorithm something like this: 
// Get the first page of data associated with our selector expression
this_page = query_api(where=YOUR_SELECTOR_EXPRESSION)
do_something_with_response(this_page)

// If we get fewer records than the page_size returned with our results,
// then there are no more records to get. Otherwise, keep querying for additional pages.
while (length of this_page.results) >= this_page.page_size:
    next_page_number = this_page.page + 1
    this_page = query_api(where=YOUR_SELECTOR_EXPRESSION, session_id=this_page.session_id, page=next_page_number)
    do_something_with_response(this_page)
The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

Authorizations

​
Authorization
string
header
required

Service Account

Query Parameters

​
project_id
integer
required

Required if using service account to authenticate request.

​
workspace_id
integer

The id of the workspace if applicable.

Body

application/x-www-form-urlencoded
​
distinct_id
string

A unique identifier used to distinguish an individual profile.

​
distinct_ids
string

A JSON array of distinct_ids to retrieve profiles for. Example: distinct_ids=["id1", "id2"]

​
data_group_id
string

The ID of the group key, used when querying group profiles, click here for more info.

​
where
string

An expression to filter users (or groups) by. See the expressions section above.

​
output_properties
string[]

A JSON array of names of properties you want returned. Example: output_properties=["$last_name", "$email", "Total Spent"]

This parameter can drastically reduce the amount of data returned by the API when you're not interested in all properties and can speed up queries significantly.

​
session_id
string

A string id provided in the results of a previous query. Using a session_id speeds up api response, and allows paging through results.

​
page
integer

Which page of the results to retrieve. Pages start at zero. If the "page" parameter is provided and above 0, the session_id parameter must also be provided.

​
behaviors
integer

If you are exporting user profiles using an event selector, you use a behaviors parameter in your request. behaviors and filter_by_cohort are mutually exclusive.

​
as_of_timestamp
integer

This parameter is only useful when also using behaviors. If you try to export more than 1k profiles using a behaviors parameter and you don't included the parameter as_of_timestamp, you'll see the following error:

request for page in uncached query for params

​
filter_by_cohort
string

Takes a JSON object with a single key called id whose value is the cohort ID. behaviors and filter_by_cohort are mutually exclusive.

Example: filter_by_cohort='{"id":12345}'

​
include_all_users
boolean

*only applicable with filter_by_cohort parameter

include_all_users=true (default) include all distinct_ids even if they don’t have a user (or group) profile.

include_all_users=false include only distinct_ids with user (or group) profile.

Response

200 - application/json

Success.

​
page
integer

The page number of the results

​
page_size
integer

The max number of results in a single page.

​
session_id
string
​
status
string

Indicates whether the request was successful

​
total
integer

The number of users in the results payload.

​
results
object[]