list_subscribers

Purpose

List members (project subscribers) with optional filters by project_id, status, and a free-text search across name, email and billing email. Results are scoped to the token's team and ordered newest-first.

Required ability

project-user:view-any

Input schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to narrow the result."
    },
    "status": {
      "type": "string",
      "description": "Member status filter. One of: lead, trialing, customer, churned, banned."
    },
    "search": {
      "type": "string",
      "description": "Case-insensitive partial match against name, email and billing email."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum members to return per page (1..100)."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "1-indexed page number."
    }
  }
}

Output shape

{
  "data": [
    {
      "id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
      "name": "Jane Doe",
      "email": "[email protected]",
      "email_verified": true,
      "billing_email": "[email protected]",
      "chat_id": "123456789",
      "status": "customer",
      "joined_at": "2026-05-18T10:05:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 41,
    "has_more": true
  }
}

Example prompts

"List churned subscribers in project 7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13."

"Search for members with 'gmail' in their email across my Research Premium project."

Failure modes

• TOKEN_MISSING_ABILITY — token lacks project-user:view-any.
• RESOURCE_NOT_FOUND — project_id names a project the token cannot see: unknown, another team's, or outside the token's scope:project: allow-list. Without a project_id, the list spans only the projects the allow-list admits.
• VALIDATION_FAILED — status is not one of the member statuses; the error context lists the supported values.

Caveats

• email and billing_email mean different things. email is an address the member chose and verified, and is their portal sign-in credential. billing_email is whatever they typed at a payment provider's checkout — never verified, never used for authentication. Do not treat a billing_email as a confirmed way to reach someone.
• Most members have email: null. They join through a bot and are never asked for one, so billing_email is often the only address on record — which is what makes it useful for matching a refund request to a subscription.
• billing_email is null for anyone who joined by redeeming an access code, because no payment ever took place. It is also null for members whose last payment predates automatic capture.

Related

• ban_member
• kick_member
• get_activity_log
• Members API