---
title: "List Users"
method: POST
path: "/v2/users/query"
tags: ["Users V2"]
---

# List Users

`POST /v2/users/query`

Query users with filters, search term, and a download flag. Returns dynamic attribute columns alongside each user row (app_user_id, a nested properties object, and flattened attributes). Requires users:read scope.

## Request body

- object
  - `application_id` string, required — Application ID
  - `filters` object[]
    - `id` string, required — Client-supplied filter identifier
    - `field_id` string, required — Field to filter on: 'user_<attributeKey>' for an attribute, 'user_appUserId' for the id, or 'event' for an event name
    - `operator` string — Comparison operator, e.g. is, isNot, contains, greaterThan, between, before
    - `values` Superwall1apiSchema1v21JsonValue[], required — Operand value(s) for the operator — unresolved $ref
  - `match_mode` 'all' | 'any' — Whether a row must match all filters or any of them
  - `search_term` string
  - `is_download` boolean — When true, raises the row limit for CSV export

## Response `200`

Success

- object
  - `object` 'user_query_result', required
  - `total` number, required — Total users in the application
  - `returned_count` number, required — Users returned in this page
  - `filtered_total` number, required — Users matching the filters after the search term is applied
  - `columns` object[], required — Ordered columns to render: app_user_id first, then attributes by frequency
    - `key` string, required
    - `type` string, required — Inferred type, e.g. String, Int64, Float64, Bool, Date
    - `count` number, required — Number of users with this attribute
  - `keys` object[], required — Attribute columns only
    - `key` string, required
    - `type` string, required — Inferred type, e.g. String, Int64, Float64, Bool, Date
    - `count` number, required — Number of users with this attribute
  - `time_elapsed` number, required — Query duration in seconds
  - `rows` Superwall1apiSchema1v21JsonObject[], required — User rows; each has app_user_id, a nested properties object, and flattened attributes — unresolved $ref

## Other responses

- `400` — The request did not match the expected schema
- `401` — No API key was provided in the request
- `403` — The API key does not have permission to perform this action
- `404` — The requested resource was not found
- `429` — Too many requests have been made in a short period
- `500` — An unexpected error occurred on the server

---

[API](https://skmtc.dev/superwall/apis/superwall-api-v2.md) · [All operations](https://skmtc.dev/superwall/apis/superwall-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/superwall/superwall-api-v2/revisions/44900ad77d2c/schema)