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

# List external users

> List end users for your project with optional channel/source filters, pagination, sorting, and credit usage totals.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/external-users
openapi: 3.0.0
info:
  title: Flowra API (API Key Endpoints)
  description: >-
    **Flowra** is an AI-powered platform for building agents, workflows, and
    integrations.


    ### Capabilities

    - **Tools & Toolkits** – Define and group tools for agents and workflows.

    - **Workflows** – Orchestrate steps and automate processes.

    - **Triggers** – Schedule or event-based execution.

    - **Auth & Connections** – OAuth, API keys, and connected accounts.

    - **MCP** – Model Context Protocol server integration.

    - **Knowledge / RAG** – Add files and URLs for retrieval-augmented
    generation.


    ### Authentication

    Use the **x-api-key** header with a project API key to access endpoints that
    support API Key auth. Create and manage API keys in the dashboard under your
    project settings.


    Only endpoints that support API Key authentication via the @ApiKeyEnabled()
    decorator.


    Send x-api-key (required). On multi-tenant endpoints, optionally send
    x-username to act as an external user.
  version: '1.0'
  contact:
    name: Flowra
    url: https://flowra.dev
servers:
  - url: https://flowra.dev
    description: Flowra API
security: []
tags:
  - name: Users
    description: User profile
  - name: External Users
    description: End-user identities inside a project (x-username)
  - name: Auth Configs
    description: OAuth and API key configs for toolkits
  - name: Connected Accounts
    description: OAuth connected accounts and link creation
  - name: Toolkits
    description: List and search toolkits
  - name: Tools
    description: List, execute, and manage tools
  - name: Skills
    description: Browse, create, import, and install skills
  - name: Workflow & Agent
    description: Create, run, and inspect workflows and agents
  - name: Triggers
    description: Schedule and event-based trigger instances
  - name: Chat
    description: Threads and streaming agent runs
  - name: File
    description: Upload, list, and download files
  - name: Knowledge
    description: RAG knowledge collections
  - name: Table
    description: Collections and documents
  - name: Sandbox
    description: Ephemeral and durable code sandboxes
  - name: Browser
    description: Live browser sessions and view
  - name: LLM
    description: List AI models and generate completions
  - name: MCP
    description: MCP server management
  - name: usage
    description: Credit balance and usage ledger for the project API key
paths:
  /api/v1/external-users:
    get:
      tags:
        - External Users
      summary: List external users
      description: >-
        List end users for your project with optional channel/source filters,
        pagination, sorting, and credit usage totals.
      operationId: ExternalUsersController_list
      parameters:
        - name: q
          required: false
          in: query
          description: Filter by username (name) with case-insensitive partial match
          schema:
            maxLength: 255
            example: alice
            type: string
        - name: channel
          required: false
          in: query
          description: Filter by messaging channel (metadata.channel, e.g. telegram)
          schema:
            maxLength: 64
            example: telegram
            type: string
        - name: source
          required: false
          in: query
          description: >-
            Filter by source. One value, comma-separated, or repeated query
            params.
          schema:
            type: array
            items:
              type: string
              enum:
                - project_default
                - username
                - embed_visitor
                - trigger_thread
                - project_runtime
        - name: isActive
          required: false
          in: query
          description: Filter by active status (omit for all)
          schema:
            type: boolean
            example: true
        - name: activeEuid
          required: false
          in: query
          description: >-
            Pin this external user id to the top of the list (current dashboard
            selection)
          schema:
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            type: string
        - name: sortBy
          required: false
          in: query
          description: Field to sort by (after pin ranking)
          schema:
            enum:
              - name
              - createdAt
              - source
              - creditsUsed
              - isActive
              - id
              - channel
              - profileSummary
              - lastSeenAt
              - agentCount
              - workflowCount
              - knowledgeStorageKb
              - databaseStorageKb
              - storageUsedKb
              - connectionCount
            type: string
        - name: sortOrder
          required: false
          in: query
          description: Sort order
          schema:
            default: ASC
            enum:
              - ASC
              - DESC
            type: string
        - name: from
          required: false
          in: query
          description: Credits sum from date (ISO 8601)
          schema:
            example: '2026-08-01T00:00:00.000Z'
            type: string
        - name: to
          required: false
          in: query
          description: Credits sum to date (ISO 8601)
          schema:
            example: '2026-09-01T00:00:00.000Z'
            type: string
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            default: 1
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items per page (max 100)
          schema:
            minimum: 1
            maximum: 100
            default: 20
            example: 20
            type: number
        - name: x-username
          in: header
          required: false
          description: >-
            External user (end user) to act as. Optional — if omitted, Flowra
            uses the project’s default external user. Send a stable username
            (e.g. customer_alice) only when you need another end-user context.
          schema:
            type: string
            default: (project default user)
          example: customer_alice
      responses:
        '200':
          description: External users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalUserResponseDtoPaginatedResponse'
              example:
                success: true
                message: Data retrieved successfully
                data:
                  - id: 123e4567-e89b-12d3-a456-426614174000
                    name: John Doe
                    projectId: 123e4567-e89b-12d3-a456-426614174000
                    source: project_default
                    isActive: true
                    channel: ''
                    profileSummary: ''
                    avatarUrl: ''
                    creditsUsed: 0
                    createdAt: ''
                    lastSeenAt: ''
                    isOnline: true
                    resourceStats:
                      agentCount: 0
                      workflowCount: 0
                      knowledgeStorageKb: 0
                      databaseStorageKb: 0
                      storageUsedKb: 0
                      connectionCount: 0
                    addedByWorkflowIds:
                      - ''
                    addedByWorkflowId: ''
                    metadata:
                      channel: telegram
                      toolkitSlug: telegram
                      toolSlug: TELEGRAM_SET_WEBHOOK
                      threadKey: '123456789'
                      profile:
                        userId: 123456789
                        username: amin
                        firstName: Amin
                      updatedAt: '2026-07-13T08:00:00.000Z'
                    verifiedEmail: ''
                    verifiedPhone: ''
                    identitySources:
                      - email
                      - host_sub
                total: 100
                totalTools: 5000
                page: 1
                limit: 20
                totalPages: 5
                hasNextPage: true
                hasPreviousPage: false
      security:
        - x-api-key: []
        - x-api-key: []
          x-username: []
components:
  schemas:
    ExternalUserResponseDtoPaginatedResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: true
        message:
          type: string
          description: Response message
          example: Data retrieved successfully
        data:
          description: Array of items
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: ID of the external user
                example: 123e4567-e89b-12d3-a456-426614174000
              name:
                type: string
                nullable: true
                description: Name of the external user
                example: John Doe
              projectId:
                type: string
                nullable: true
                description: Project ID
                example: 123e4567-e89b-12d3-a456-426614174000
              source:
                enum:
                  - project_default
                  - username
                  - embed_visitor
                  - trigger_thread
                  - project_runtime
                type: string
                description: How this external user was created
              isActive:
                type: boolean
                description: >-
                  Whether this external user can act on the project (API /
                  channels)
                default: true
              channel:
                type: string
                nullable: true
                description: Messaging channel key from metadata (e.g. telegram)
              profileSummary:
                type: string
                nullable: true
                description: Short profile summary from metadata.profile
              avatarUrl:
                type: string
                nullable: true
                description: >-
                  Profile photo URL from metadata.profile (`https` or
                  `file:<uuid>`)
              creditsUsed:
                type: number
                description: >-
                  Sum of credit_usage_log.creditAmount for this eUID
                  (forward-attributed only)
                default: 0
              createdAt:
                type: string
                description: When this external user was created (membership date)
              lastSeenAt:
                type: string
                nullable: true
                description: >-
                  Last activity: max of lastSeenAt, channel metadata.updatedAt,
                  and last credit usage
              isOnline:
                type: boolean
                description: True when lastSeenAt is within the last 5 minutes
                default: false
              resourceStats:
                type: object
                properties:
                  agentCount:
                    type: number
                    description: Number of agent workflows owned by this eUID
                    default: 0
                  workflowCount:
                    type: number
                    description: Number of static workflows owned by this eUID
                    default: 0
                  knowledgeStorageKb:
                    type: number
                    description: >-
                      Estimated knowledge (vector) storage used in KiB for this
                      eUID
                    default: 0
                  databaseStorageKb:
                    type: number
                    description: Estimated database storage used in KiB for this eUID
                    default: 0
                  storageUsedKb:
                    type: number
                    description: Total file storage used in KiB
                    default: 0
                  connectionCount:
                    type: number
                    description: Number of connected accounts for this eUID
                    default: 0
                required:
                  - agentCount
                  - workflowCount
                  - knowledgeStorageKb
                  - databaseStorageKb
                  - storageUsedKb
                  - connectionCount
              addedByWorkflowIds:
                description: >-
                  Workflow/agent ids linked to this end-user (from
                  external_user_workflow_links).
                type: array
                items:
                  type: string
              addedByWorkflowId:
                type: string
                nullable: true
                description: First linked workflow/agent id (addedByWorkflowIds[0]).
                deprecated: true
              metadata:
                type: object
                nullable: true
                description: >-
                  Channel profile / trigger context (e.g. Telegram username).
                  Present for messaging-channel users.
                example:
                  channel: telegram
                  toolkitSlug: telegram
                  toolSlug: TELEGRAM_SET_WEBHOOK
                  threadKey: '123456789'
                  profile:
                    userId: 123456789
                    username: amin
                    firstName: Amin
                  updatedAt: '2026-07-13T08:00:00.000Z'
              verifiedEmail:
                type: string
                nullable: true
                description: Verified email claim from external_user_identities, if any.
              verifiedPhone:
                type: string
                nullable: true
                description: >-
                  Verified phone claim (E.164) from external_user_identities, if
                  any.
              identitySources:
                description: Verified identity kinds attached to this eUID.
                example:
                  - email
                  - host_sub
                type: array
                items:
                  type: string
            required:
              - id
              - name
              - projectId
              - source
              - isActive
          example:
            - id: 123e4567-e89b-12d3-a456-426614174000
              name: John Doe
              projectId: 123e4567-e89b-12d3-a456-426614174000
              source: project_default
              isActive: true
              channel: ''
              profileSummary: ''
              avatarUrl: ''
              creditsUsed: 0
              createdAt: ''
              lastSeenAt: ''
              isOnline: true
              resourceStats:
                agentCount: 0
                workflowCount: 0
                knowledgeStorageKb: 0
                databaseStorageKb: 0
                storageUsedKb: 0
                connectionCount: 0
              addedByWorkflowIds:
                - ''
              addedByWorkflowId: ''
              metadata:
                channel: telegram
                toolkitSlug: telegram
                toolSlug: TELEGRAM_SET_WEBHOOK
                threadKey: '123456789'
                profile:
                  userId: 123456789
                  username: amin
                  firstName: Amin
                updatedAt: '2026-07-13T08:00:00.000Z'
              verifiedEmail: ''
              verifiedPhone: ''
              identitySources:
                - email
                - host_sub
        total:
          type: number
          description: Total number of items across all pages
          example: 100
        totalTools:
          type: number
          description: >-
            Optional secondary total (e.g. nested tools across all matching
            toolkits)
          example: 5000
        page:
          type: number
          description: Current page number (1-based)
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 5
        hasNextPage:
          type: boolean
          description: Whether there is a next page
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there is a previous page
          example: false
      required:
        - success
        - message
        - data
        - total
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Project API key. Create and manage keys in the dashboard under Project →
        API Keys. Send as header: x-api-key: <your-key>
    x-username:
      type: apiKey
      in: header
      name: x-username
      description: >-
        Optional. External user username. If omitted, Flowra uses the project’s
        default external user. Send as header: x-username: <username>

````

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