> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grail.oro.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# List Users

> Lists users for the authenticated partner, with optional filters.

## Overview

Returns a partner-scoped list of users in reverse-chronological order (newest first). All filters are optional; omit them to list every user belonging to the partner.

The list response is intentionally minimal — it does not include KYC detail. For full KYC data on a specific user, call [Get User](/api-reference/users/get-user).

## Headers

<ParamField header="x-api-key" type="string" required>
  A valid `PARTNER` scope key.
</ParamField>

## Query Parameters

<ParamField query="status" type="string">
  Filter by user status: `"active"` or `"suspended"`.
</ParamField>

<ParamField query="user_id" type="string">
  Reverse-lookup by your own `user_id` (the `partner_user_id` supplied at creation). Since this pair is unique per partner, the response contains at most one user.
</ParamField>

## Response

<ResponseField name="users" type="array">
  Array of user objects. Each object:

  <Expandable title="properties">
    <ResponseField name="grail_user_id" type="string">
      GRAIL's identifier for the user, prefixed `gu_`.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      Your internal identifier (the `partner_user_id` supplied at creation).
    </ResponseField>

    <ResponseField name="wallet_address" type="string">
      The user's Solana wallet address.
    </ResponseField>

    <ResponseField name="status" type="string">
      `"active"` or `"suspended"`. Suspended users cannot quote trades or redemptions.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO-8601 timestamp of user creation.
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| HTTP | `error`        | When                           |
| ---- | -------------- | ------------------------------ |
| 401  | `unauthorized` | Missing or invalid `x-api-key` |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://grail-stack-dev.onrender.com/v1/users?status=active" \
    -H "x-api-key: grail_partner_<hex>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "users": [
      {
        "grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
        "user_id": "partner_internal_user_001",
        "wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
        "status": "active",
        "created_at": "2026-04-17T10:15:30.000Z"
      }
    ]
  }
  ```
</ResponseExample>