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

# Get and list users

> GET /v1/platform-users and GET /v1/platform-users/list: one platform user by external_id or csid_id, or all your platform users, newest first.

Read one of your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md) by your own id, or page through all of them. The user object carries the identity, the wallets with their trust status, X, Telegram, the KOL badge and open wallet verifications. Trading data is in the [profile](https://docs.cabalspy.xyz/cabalspy-id/platform-users-profile.md).

## Get a user

`GET /v1/platform-users`

### Query Parameters

**external\_id** `string`

Your id of the user. Pass this or csid\_id.

**csid\_id** `string`

The user's CabalSpy ID account id.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

### Usage Example

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/platform-users?external_id=user_8412" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

r = requests.get("https://api-id.cabalspy.xyz/v1/platform-users",
                 params={"external_id": "user_8412"},
                 headers={"Authorization": "Bearer YOUR_KEY"})
u = r.json()["data"]
print(u["csid_id"], [(w["address"], w["status"]) for w in u["wallets"]])
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({ external_id: "user_8412" });
const res = await fetch(`https://api-id.cabalspy.xyz/v1/platform-users?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
console.log(data.csid_id, data.wallets.map(w => w.status));
```

### Response

**success** `boolean`

True on success.

**data** `object`

**user**

**csid\_id** `string`

The CabalSpy ID account id. Changes to the person's own account id when they claim it.

**external\_id** `string`

Your id of the user.

**claimed** `boolean`

Whether the person took the account into their own CabalSpy ID with a [claim link](https://docs.cabalspy.xyz/cabalspy-id/platform-users-claim.md).

**claimed\_at** `string`

When it was claimed, or null.

**managed** `boolean`

True while the account is managed by your instance, false after a claim.

**display\_name** `string`

Display name, or null.

**avatar\_url** `string`

Avatar URL, or null.

**limited** `boolean`

True when the user has no seat in your plan's user limit, so you receive no data for them.

**x** `object`

Connected X account, or null: id, username, name, avatar\_url, followers, following, verified, verified\_type, created\_at (of the X account) and url.

**telegram** `object`

Linked Telegram account, or null: username, name and linked\_at.

**kol** `object`

badge (boolean) and since (when it was granted, or null).

**wallets** `array`

**wallet**

**address** `string`

Wallet address.

**family** `string`

solana or evm.

**chains** `array`

Every chain the wallet is tracked or verified on.

**verified** `boolean`

Whether it is payment-verified on at least one chain.

**verified\_chains** `array`

Chains it is payment-verified on.

**status** `string`

verified, active, needs\_verification, verified\_elsewhere or pending. See [Unverified and verified wallets](https://docs.cabalspy.xyz/cabalspy-id/white-label.md#unverified-and-verified-wallets).

**counts** `boolean`

Whether the wallet counts for data, profiles and leaderboards (status verified or active).

**source** `string`

The source you sent with the wallet, or null.

**verified\_at** `string`

When it was verified, or null.

**added\_at** `string`

When it was added.

**pending\_verifications** `array`

Open payment verifications, each the [verification object](https://docs.cabalspy.xyz/cabalspy-id/platform-users-verification.md#response).

**created\_at** `string`

When you added the user.

```json Response theme={null}
{
  "success": true,
  "data": {
    "csid_id": "3f9a1c2e-5b7d-4e8f-a1b2-c3d4e5f60718",
    "external_id": "user_8412",
    "claimed": false,
    "claimed_at": null,
    "managed": true,
    "display_name": "Maze",
    "avatar_url": "https://cdn.example.com/avatars/8412.png",
    "limited": false,
    "x": null,
    "telegram": null,
    "kol": { "badge": false, "since": null },
    "wallets": [
      {
        "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "family": "solana",
        "chains": ["solana"],
        "verified": false,
        "verified_chains": [],
        "status": "active",
        "counts": true,
        "source": "privy",
        "verified_at": null,
        "added_at": "2026-10-24T09:12:40Z"
      },
      {
        "address": "0x4b1e9c0d2a7f3e5b8c6d1a9f0e2b7c4d5a6e8f01",
        "family": "evm",
        "chains": ["base", "bnb", "eth", "rh"],
        "verified": true,
        "verified_chains": ["base"],
        "status": "verified",
        "counts": true,
        "source": null,
        "verified_at": "2026-10-25T16:02:11Z",
        "added_at": "2026-10-24T09:12:40Z"
      }
    ],
    "pending_verifications": [],
    "created_at": "2026-10-24T09:12:40Z"
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}
```

## List users

`GET /v1/platform-users/list`

All platform users of your instance, newest first, each as the user object above.

> [!TIP]
>
> Read pagination.next\_cursor from the response and pass it back as cursor to fetch the next page. When next\_cursor is null you have reached the end.

### Query Parameters

**limit** `integer` (default: 50)

Users per page, 1 to 100.

**cursor** `string`

Cursor for the next page, the pagination.next\_cursor from the previous response. A malformed cursor is answered with 400 invalid\_parameter.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

### Usage Example

```bash cURL theme={null}
curl "https://api-id.cabalspy.xyz/v1/platform-users/list?limit=100" \
  -H "Authorization: Bearer YOUR_KEY"
```

```python Python theme={null}
import requests

H = {"Authorization": "Bearer YOUR_KEY"}
params = {"limit": 100}
while True:
    r = requests.get("https://api-id.cabalspy.xyz/v1/platform-users/list", params=params, headers=H).json()
    for u in r["data"]:
        print(u["external_id"], len(u["wallets"]), "wallets")
    if not r["pagination"]["next_cursor"]:
        break
    params["cursor"] = r["pagination"]["next_cursor"]
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({ limit: "100" });
const res = await fetch(`https://api-id.cabalspy.xyz/v1/platform-users/list?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data, pagination } = await res.json();
console.log(data.length, pagination.total, pagination.next_cursor);
```

### Response

`data` is an array of user objects. `pagination` has limit, total (all platform users of the instance), has\_more and next\_cursor.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | Neither external\_id nor csid\_id was passed. |
| 400 | invalid\_parameter | external\_id, csid\_id, limit or cursor invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 404 | platform\_user\_not\_found | No user with this id in your instance. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.