list_subscribers

Paginated list of project members with optional filters by project, status, and free-text search.

Purpose

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

Emails are returned verbatim. Scrub before forwarding to external systems.

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."
    },
    "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": "usr_01HX...",
      "project_id": "prj_01HX...",
      "name": "Jane Doe",
      "email": "[email protected]",
      "email_verified": true,
      "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 prj_01HX...."

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

Failure modes

TOKEN_MISSING_ABILITY — token lacks project-user:view-any.