Query users

Note: This endpoint may be subject to changes.

POST https://api.ap1.datadoghq.com/api/v2/product-analytics/users/queryhttps://api.ap2.datadoghq.com/api/v2/product-analytics/users/queryhttps://api.datadoghq.eu/api/v2/product-analytics/users/queryhttps://api.ddog-gov.com/api/v2/product-analytics/users/queryhttps://api.us2.ddog-gov.com/api/v2/product-analytics/users/queryhttps://api.datadoghq.com/api/v2/product-analytics/users/queryhttps://api.us3.datadoghq.com/api/v2/product-analytics/users/queryhttps://api.us5.datadoghq.com/api/v2/product-analytics/users/query

Overview

Query users with flexible filtering by user properties, with optional wildcard search

Request

Body Data (required)

Expand All

Field

Type

Description

data

object

The data object containing the resource type and attributes for querying users.

attributes

object

Attributes for filtering and shaping the user query results.

limit

int64

Maximum number of user records to return in the response.

query

string

Filter expression using user attribute conditions to narrow results.

select_columns

[string]

List of user attribute column names to include in the response.

sort

object

Sorting configuration specifying the field and direction for ordering user query results.

field

string

The user attribute field name to sort results by.

order

string

The sort direction, either ascending or descending.

wildcard_search_term

string

Free-text term used for wildcard search across user attribute values.

id

string

Unique identifier for the query users request resource.

type [required]

enum

Query users request resource type. Allowed enum values: query_users_request

default: query_users_request

{
  "data": {
    "attributes": {
      "limit": "integer",
      "query": "string",
      "select_columns": [],
      "sort": {
        "field": "string",
        "order": "string"
      },
      "wildcard_search_term": "string"
    },
    "id": "string",
    "type": "query_users_request"
  }
}

Response

Successful response with user data

Response containing the query results with matched records and total count.

Expand All

Field

Type

Description

data

object

The data object containing the resource type and attributes of the query response.

attributes

object

Attributes of the query response, containing the matched records and total count.

hits

[]

The list of matching records returned by the query, each as a map of attribute names to values.

total

int64

Total number of records matching the query, regardless of the limit applied.

id

string

Unique identifier for the query response resource.

type [required]

enum

Query response resource type. Allowed enum values: query_response

default: query_response

{
  "data": {
    "attributes": {
      "hits": [
        {
          "first_browser_name": "Chrome",
          "first_city": "San Francisco",
          "first_country_code": "US",
          "first_device_type": "Desktop",
          "last_seen": "2025-08-14T06:45:12.142Z",
          "session_count": 47,
          "user_created": "2024-12-15T08:42:33.287Z",
          "user_email": "john.smith@techcorp.com",
          "user_id": "150847",
          "user_name": "John Smith",
          "user_org_id": "5001"
        },
        {
          "first_browser_name": "Chrome",
          "first_city": "Austin",
          "first_country_code": "US",
          "first_device_type": "Desktop",
          "last_seen": "2025-08-14T05:22:08.951Z",
          "session_count": 89,
          "user_created": "2024-11-28T14:17:45.634Z",
          "user_email": "john.williams@techcorp.com",
          "user_id": "150848",
          "user_name": "John Williams",
          "user_org_id": "5001"
        },
        {
          "first_browser_name": "Chrome",
          "first_city": "Seattle",
          "first_country_code": "US",
          "first_device_type": "Desktop",
          "last_seen": "2025-08-14T04:18:34.726Z",
          "session_count": 23,
          "user_created": "2025-01-03T16:33:21.445Z",
          "user_email": "john.jones@techcorp.com",
          "user_id": "150849",
          "user_name": "John Jones",
          "user_org_id": "5001"
        }
      ],
      "total": 147
    },
    "id": "query_response",
    "type": "query_response"
  }
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  ## default
# 

# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/product-analytics/users/query" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "limit": 25, "query": "user_email:*@techcorp.com AND first_country_code:US AND first_browser_name:Chrome", "select_columns": [ "user_id", "user_email", "user_name", "user_org_id", "first_country_code", "first_browser_name", "first_device_type", "last_seen" ], "sort": { "field": "first_seen", "order": "DESC" }, "wildcard_search_term": "john" }, "id": "query_users_request", "type": "query_users_request" } } EOF
"""
Query users returns "Successful response with user data" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.rum_audience_management_api import RumAudienceManagementApi
from datadog_api_client.v2.model.query_users_request import QueryUsersRequest
from datadog_api_client.v2.model.query_users_request_data import QueryUsersRequestData
from datadog_api_client.v2.model.query_users_request_data_attributes import QueryUsersRequestDataAttributes
from datadog_api_client.v2.model.query_users_request_data_attributes_sort import QueryUsersRequestDataAttributesSort
from datadog_api_client.v2.model.query_users_request_data_type import QueryUsersRequestDataType

body = QueryUsersRequest(
    data=QueryUsersRequestData(
        attributes=QueryUsersRequestDataAttributes(
            limit=25,
            query="user_email:*@techcorp.com AND first_country_code:US AND first_browser_name:Chrome",
            select_columns=[
                "user_id",
                "user_email",
                "user_name",
                "user_org_id",
                "first_country_code",
                "first_browser_name",
                "first_device_type",
                "last_seen",
            ],
            sort=QueryUsersRequestDataAttributesSort(
                field="first_seen",
                order="DESC",
            ),
            wildcard_search_term="john",
        ),
        id="query_users_request",
        type=QueryUsersRequestDataType.QUERY_USERS_REQUEST,
    ),
)

configuration = Configuration()
configuration.unstable_operations["query_users"] = True
with ApiClient(configuration) as api_client:
    api_instance = RumAudienceManagementApi(api_client)
    response = api_instance.query_users(body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Query users returns "Successful response with user data" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.query_users".to_sym] = true
end
api_instance = DatadogAPIClient::V2::RumAudienceManagementAPI.new

body = DatadogAPIClient::V2::QueryUsersRequest.new({
  data: DatadogAPIClient::V2::QueryUsersRequestData.new({
    attributes: DatadogAPIClient::V2::QueryUsersRequestDataAttributes.new({
      limit: 25,
      query: "user_email:*@techcorp.com AND first_country_code:US AND first_browser_name:Chrome",
      select_columns: [
        "user_id",
        "user_email",
        "user_name",
        "user_org_id",
        "first_country_code",
        "first_browser_name",
        "first_device_type",
        "last_seen",
      ],
      sort: DatadogAPIClient::V2::QueryUsersRequestDataAttributesSort.new({
        field: "first_seen",
        order: "DESC",
      }),
      wildcard_search_term: "john",
    }),
    id: "query_users_request",
    type: DatadogAPIClient::V2::QueryUsersRequestDataType::QUERY_USERS_REQUEST,
  }),
})
p api_instance.query_users(body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// Query users returns "Successful response with user data" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	body := datadogV2.QueryUsersRequest{
		Data: &datadogV2.QueryUsersRequestData{
			Attributes: &datadogV2.QueryUsersRequestDataAttributes{
				Limit: datadog.PtrInt64(25),
				Query: datadog.PtrString("user_email:*@techcorp.com AND first_country_code:US AND first_browser_name:Chrome"),
				SelectColumns: []string{
					"user_id",
					"user_email",
					"user_name",
					"user_org_id",
					"first_country_code",
					"first_browser_name",
					"first_device_type",
					"last_seen",
				},
				Sort: &datadogV2.QueryUsersRequestDataAttributesSort{
					Field: datadog.PtrString("first_seen"),
					Order: datadog.PtrString("DESC"),
				},
				WildcardSearchTerm: datadog.PtrString("john"),
			},
			Id:   datadog.PtrString("query_users_request"),
			Type: datadogV2.QUERYUSERSREQUESTDATATYPE_QUERY_USERS_REQUEST,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.QueryUsers", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewRumAudienceManagementApi(apiClient)
	resp, r, err := api.QueryUsers(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `RumAudienceManagementApi.QueryUsers`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `RumAudienceManagementApi.QueryUsers`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// Query users returns "Successful response with user data" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.RumAudienceManagementApi;
import com.datadog.api.client.v2.model.QueryResponse;
import com.datadog.api.client.v2.model.QueryUsersRequest;
import com.datadog.api.client.v2.model.QueryUsersRequestData;
import com.datadog.api.client.v2.model.QueryUsersRequestDataAttributes;
import com.datadog.api.client.v2.model.QueryUsersRequestDataAttributesSort;
import com.datadog.api.client.v2.model.QueryUsersRequestDataType;
import java.util.Arrays;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.queryUsers", true);
    RumAudienceManagementApi apiInstance = new RumAudienceManagementApi(defaultClient);

    QueryUsersRequest body =
        new QueryUsersRequest()
            .data(
                new QueryUsersRequestData()
                    .attributes(
                        new QueryUsersRequestDataAttributes()
                            .limit(25L)
                            .query(
                                "user_email:*@techcorp.com AND first_country_code:US AND"
                                    + " first_browser_name:Chrome")
                            .selectColumns(
                                Arrays.asList(
                                    "user_id",
                                    "user_email",
                                    "user_name",
                                    "user_org_id",
                                    "first_country_code",
                                    "first_browser_name",
                                    "first_device_type",
                                    "last_seen"))
                            .sort(
                                new QueryUsersRequestDataAttributesSort()
                                    .field("first_seen")
                                    .order("DESC"))
                            .wildcardSearchTerm("john"))
                    .id("query_users_request")
                    .type(QueryUsersRequestDataType.QUERY_USERS_REQUEST));

    try {
      QueryResponse result = apiInstance.queryUsers(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling RumAudienceManagementApi#queryUsers");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// Query users returns "Successful response with user data" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_rum_audience_management::RumAudienceManagementAPI;
use datadog_api_client::datadogV2::model::QueryUsersRequest;
use datadog_api_client::datadogV2::model::QueryUsersRequestData;
use datadog_api_client::datadogV2::model::QueryUsersRequestDataAttributes;
use datadog_api_client::datadogV2::model::QueryUsersRequestDataAttributesSort;
use datadog_api_client::datadogV2::model::QueryUsersRequestDataType;

#[tokio::main]
async fn main() {
    let body =
        QueryUsersRequest
        ::new().data(
            QueryUsersRequestData::new(QueryUsersRequestDataType::QUERY_USERS_REQUEST)
                .attributes(
                    QueryUsersRequestDataAttributes::new()
                        .limit(25)
                        .query(
                            "user_email:*@techcorp.com AND first_country_code:US AND first_browser_name:Chrome".to_string(),
                        )
                        .select_columns(
                            vec![
                                "user_id".to_string(),
                                "user_email".to_string(),
                                "user_name".to_string(),
                                "user_org_id".to_string(),
                                "first_country_code".to_string(),
                                "first_browser_name".to_string(),
                                "first_device_type".to_string(),
                                "last_seen".to_string()
                            ],
                        )
                        .sort(
                            QueryUsersRequestDataAttributesSort::new()
                                .field("first_seen".to_string())
                                .order("DESC".to_string()),
                        )
                        .wildcard_search_term("john".to_string()),
                )
                .id("query_users_request".to_string()),
        );
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.QueryUsers", true);
    let api = RumAudienceManagementAPI::with_config(configuration);
    let resp = api.query_users(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Query users returns "Successful response with user data" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.queryUsers"] = true;
const apiInstance = new v2.RumAudienceManagementApi(configuration);

const params: v2.RumAudienceManagementApiQueryUsersRequest = {
  body: {
    data: {
      attributes: {
        limit: 25,
        query:
          "user_email:*@techcorp.com AND first_country_code:US AND first_browser_name:Chrome",
        selectColumns: [
          "user_id",
          "user_email",
          "user_name",
          "user_org_id",
          "first_country_code",
          "first_browser_name",
          "first_device_type",
          "last_seen",
        ],
        sort: {
          field: "first_seen",
          order: "DESC",
        },
        wildcardSearchTerm: "john",
      },
      id: "query_users_request",
      type: "query_users_request",
    },
  },
};

apiInstance
  .queryUsers(params)
  .then((data: v2.QueryResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"