Skip to main content
GET
/
v1
/
users
curl "https://grail-stack-dev.onrender.com/v1/users?status=active" \
  -H "x-api-key: grail_partner_<hex>"

{
  "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"
    }
  ]
}

​
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.

​
Headers

​
x-api-key
string
required
A valid PARTNER scope key.

​
Query Parameters

​
status
string
Filter by user status: "active" or "suspended".
​
user_id
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.

​
Response

​
users
array
Array of user objects. Each object:

​
Errors

HTTPerrorWhen
401unauthorizedMissing or invalid x-api-key
curl "https://grail-stack-dev.onrender.com/v1/users?status=active" \
  -H "x-api-key: grail_partner_<hex>"

{
  "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"
    }
  ]
}