api.botsubscription.com

GET/v1/endpoint

AuthenticationBearer

Token

Stays in this tab. Required for this endpoint — the value below is what gets sent.

Path parameters0

Query parameters0

Headers0

BodyJSON

Examples

curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

List Users - Retrieve All Bot Members via API

Retrieve a paginated list of all users who have interacted with your subscription bot. This endpoint returns user details including activity timestamps, admin status, and wallet balance, making it useful for member management and analytics dashboards.

GET/v2/projects/{project_id}/users

Authorization

Bearer API KeyRequired

API key access: Unrestricted project API key required. Restricted keys cannot call this endpoint.

Path Parameters

project_idstringrequired

The unique identifier of the project.

Query Parameters

limitintegerDefault: 10

Number of items per page, from 1 to 100.

offsetintegerDefault: 0

Number of items to skip; must be zero or greater.

status and status[] are not supported filters. Supplying either returns 422 VALIDATION_ERROR; older requests using these parameters did not filter the results. Use the membership list when you need to inspect memberships.

curl -X GET "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/users?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

const project_id = 'YOUR_PROJECT_ID';
const response = await fetch(`https://api.botsubscription.com/v2/projects/${project_id}/users?limit=10&offset=0`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

import requests
 
project_id = 'YOUR_PROJECT_ID'
response = requests.get(
    f'https://api.botsubscription.com/v2/projects/{project_id}/users',
    params={'limit': 10, 'offset': 0},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

$project_id = 'YOUR_PROJECT_ID';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.botsubscription.com/v2/projects/{$project_id}/users?limit=10&offset=0");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Successapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/users",
  "code": 200,
  "total": 3,
  "limit": 10,
  "offset": 0,
  "message": "Users retrieved successfully",
  "data": [
    {
      "user_id": "123456789012345678",
      "user_first_seen": "2025-01-15T10:30:00.000Z",
      "user_last_seen": "2025-01-20T14:00:00.000Z",
      "is_admin": true,
      "is_banned": false,
      "user_name": {
        "first_name": "John",
        "username": "johndoe"
      },
      "balance": "0",
      "currency": "USD"
    },
    {
      "user_id": "987654321098765432",
      "user_first_seen": "2025-01-10T08:15:00.000Z",
      "user_last_seen": "2025-01-18T18:30:00.000Z",
      "is_admin": false,
      "is_banned": false,
      "user_name": {
        "first_name": "Jane",
        "username": "janesmith"
      },
      "balance": "25.50",
      "currency": "USD"
    }
  ]
}

Invalid page limitapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/users",
  "code": 422,
  "errors": [
    {
      "message": "query: limit is too small; minimum allowed is 1",
      "error_code": "VALIDATION_ERROR"
    }
  ]
}

Invalid or expired API keyapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/users",
  "code": 401,
  "error": {
    "message": "Invalid or expired authentication token.",
    "error_code": "UNAUTHORIZED"
  }
}

Last updated: November 4, 2026