> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List connected accounts with optional filters

> Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v3.1/connected_accounts
openapi: 3.1.0
info:
  version: 3.1.0
  title: Composio Platform API v3.1
  description: >-
    Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints
    default to the latest tool version.
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
  - url: https://backend.composio.dev
    description: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/connected_accounts:
    get:
      tags:
        - Connected Accounts
      summary: List connected accounts with optional filters
      description: >-
        Retrieves all connected accounts for your project. Connected accounts
        represent authenticated user connections to external services (e.g., a
        user's Gmail account, Slack workspace). Filter by toolkit, status, user
        ID, or auth config to find specific connections.
      operationId: getConnectedAccounts
      parameters:
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
            description: The toolkit slugs of the connected accounts
          required: false
          description: The toolkit slugs of the connected accounts
          name: toolkit_slugs
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
              enum:
                - INITIALIZING
                - INITIATED
                - ACTIVE
                - FAILED
                - EXPIRED
                - INACTIVE
                - REVOKED
            description: The status of the connected account
          required: false
          description: The status of the connected account
          name: statuses
          in: query
        - schema:
            type:
              - string
              - 'null'
            description: The cursor to paginate through the connected accounts
          required: false
          description: The cursor to paginate through the connected accounts
          name: cursor
          in: query
        - schema:
            type:
              - number
              - 'null'
            description: The limit of the connected accounts to return
          required: false
          description: The limit of the connected accounts to return
          name: limit
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
            description: The user ids of the connected accounts
          required: false
          description: The user ids of the connected accounts
          name: user_ids
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
              format: authConfigId
            description: The auth config ids of the connected accounts
          required: false
          description: The auth config ids of the connected accounts
          name: auth_config_ids
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
              format: connectedAccountId
            description: The connected account ids to filter by
          required: false
          description: The connected account ids to filter by
          name: connected_account_ids
          in: query
        - schema:
            type: string
            enum:
              - created_at
              - updated_at
            default: created_at
            description: The order by of the connected accounts
          required: false
          description: The order by of the connected accounts
          name: order_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            description: The order direction of the connected accounts
          required: false
          description: The order direction of the connected accounts
          name: order_direction
          in: query
        - schema:
            type: string
            enum:
              - PRIVATE
              - SHARED
              - ALL
            description: >-
              [Experimental] Filter by sharing model. Default (omitted) returns
              PRIVATE only — shared accounts must be requested explicitly. Pass
              SHARED for only shared accounts, or ALL for PRIVATE + SHARED.
            x-experimental: true
          required: false
          description: >-
            [Experimental] Filter by sharing model. Default (omitted) returns
            PRIVATE only — shared accounts must be requested explicitly. Pass
            SHARED for only shared accounts, or ALL for PRIVATE + SHARED.
          name: account_type
          in: query
      responses:
        '200':
          description: Successfully retrieved connected accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        toolkit:
                          type: object
                          properties:
                            slug:
                              type: string
                              description: The slug of the toolkit
                          required:
                            - slug
                        auth_config:
                          type: object
                          properties:
                            id:
                              type: string
                              format: authConfigId
                              description: The id of the auth config
                            auth_scheme:
                              type: string
                              enum:
                                - OAUTH2
                                - OAUTH1
                                - API_KEY
                                - BASIC
                                - BILLCOM_AUTH
                                - BEARER_TOKEN
                                - GOOGLE_SERVICE_ACCOUNT
                                - NO_AUTH
                                - BASIC_WITH_JWT
                                - CALCOM_AUTH
                                - SERVICE_ACCOUNT
                                - SAML
                                - DCR_OAUTH
                                - CIMD_OAUTH
                                - S2S_OAUTH2
                              description: >-
                                the authScheme is part of the connection state
                                use it there
                              deprecated: true
                            is_composio_managed:
                              type: boolean
                              description: Whether the auth config is managed by Composio
                            is_disabled:
                              type: boolean
                              description: Whether the auth config is disabled
                          required:
                            - id
                            - auth_scheme
                            - is_composio_managed
                            - is_disabled
                        id:
                          type: string
                          format: connectedAccountId
                          description: The id of the connection
                        authScheme:
                          type: string
                          enum:
                            - OAUTH2
                            - OAUTH1
                            - API_KEY
                            - BASIC
                            - BILLCOM_AUTH
                            - BEARER_TOKEN
                            - GOOGLE_SERVICE_ACCOUNT
                            - NO_AUTH
                            - BASIC_WITH_JWT
                            - CALCOM_AUTH
                            - SERVICE_ACCOUNT
                            - SAML
                            - DCR_OAUTH
                            - CIMD_OAUTH
                            - S2S_OAUTH2
                          description: >-
                            Duplicates state.authScheme. Kept for backward
                            compatibility with existing readers; use
                            state.authScheme instead.
                          deprecated: true
                        word_id:
                          type:
                            - string
                            - 'null'
                          description: >-
                            A short, token-friendly identifier for multi-account
                            disambiguation, typically toolkit-prefixed with 1-2
                            words (e.g., "gmail_red-castle")
                        alias:
                          type:
                            - string
                            - 'null'
                          description: A user-defined alias for the connected account
                        user_id:
                          type: string
                          description: >-
                            This is deprecated, we will not be providing userId
                            from this api anymore, you will only be able to read
                            via userId not get it back
                          deprecated: true
                        status:
                          type: string
                          enum:
                            - INITIALIZING
                            - INITIATED
                            - ACTIVE
                            - FAILED
                            - EXPIRED
                            - INACTIVE
                            - REVOKED
                          description: The status of the connection
                        experimental:
                          type: object
                          properties:
                            account_type:
                              type: string
                              enum:
                                - PRIVATE
                                - SHARED
                              description: >-
                                Sharing model for this connected account.
                                PRIVATE is usable only by the owning user_id.
                                SHARED is reachable from a tool-router session
                                only when explicitly pinned in the session
                                config.
                              x-experimental: true
                            acl_config_for_shared:
                              type: object
                              properties:
                                allow_all_users:
                                  type: boolean
                                allowed_user_ids:
                                  type: array
                                  items:
                                    type: string
                                not_allowed_user_ids:
                                  type: array
                                  items:
                                    type: string
                              required:
                                - allow_all_users
                                - allowed_user_ids
                                - not_allowed_user_ids
                              description: >-
                                Access control for SHARED connections. Visible
                                only to the connection creator and project/org
                                API key callers; non-creator cookie callers
                                receive the response without this block.
                              x-experimental: true
                          required:
                            - account_type
                          description: >-
                            Experimental features - not stable, may be modified
                            or removed in future versions.
                          x-experimental: true
                        created_at:
                          type: string
                          description: The created at of the connection
                        updated_at:
                          type: string
                          description: The updated at of the connection
                        state:
                          description: The state of the connection
                          type: object
                          properties:
                            authScheme:
                              type: string
                              enum:
                                - OAUTH1
                                - OAUTH2
                                - API_KEY
                                - BASIC
                                - BEARER_TOKEN
                                - GOOGLE_SERVICE_ACCOUNT
                                - NO_AUTH
                                - CALCOM_AUTH
                                - BILLCOM_AUTH
                                - BASIC_WITH_JWT
                                - SERVICE_ACCOUNT
                                - SAML
                                - DCR_OAUTH
                                - CIMD_OAUTH
                                - S2S_OAUTH2
                            val:
                              type: object
                              properties:
                                subdomain:
                                  type: string
                                your-domain:
                                  type: string
                                region:
                                  type: string
                                shop:
                                  type: string
                                account_url:
                                  type: string
                                COMPANYDOMAIN:
                                  type: string
                                extension:
                                  type: string
                                form_api_base_url:
                                  type: string
                                instanceEndpoint:
                                  type: string
                                api_url:
                                  type: string
                                borneo_dashboard_url:
                                  type: string
                                proxy_username:
                                  type: string
                                proxy_password:
                                  type: string
                                domain:
                                  type: string
                                version:
                                  type: string
                                dc:
                                  type: string
                                site_name:
                                  type: string
                                instanceName:
                                  type: string
                                account_id:
                                  type: string
                                your_server:
                                  type: string
                                server_location:
                                  type: string
                                base_url:
                                  type: string
                                displayName:
                                  type: string
                                status:
                                  type: string
                                  enum:
                                    - INITIALIZING
                                    - INITIATED
                                    - ACTIVE
                                    - FAILED
                                    - EXPIRED
                                    - INACTIVE
                                oauth_token:
                                  type: string
                                authUri:
                                  type: string
                                oauth_token_secret:
                                  type: string
                                redirectUrl:
                                  type: string
                                callbackUrl:
                                  type: string
                                oauth_verifier:
                                  type: string
                                consumer_key:
                                  type: string
                                callback_url:
                                  type: string
                                error:
                                  type: string
                                error_description:
                                  type: string
                                expired_at:
                                  type: string
                              additionalProperties: true
                              required:
                                - status
                          additionalProperties: true
                          required:
                            - authScheme
                            - val
                        data:
                          type: object
                          additionalProperties: {}
                          description: This is deprecated, use `state` instead
                          deprecated: true
                        status_reason:
                          type:
                            - string
                            - 'null'
                          description: The reason the connection status changed.
                        is_disabled:
                          type: boolean
                          description: Whether the connection is disabled
                        test_request_endpoint:
                          type: string
                          description: The endpoint to make test request for verification
                      required:
                        - toolkit
                        - auth_config
                        - id
                        - word_id
                        - alias
                        - user_id
                        - status
                        - created_at
                        - updated_at
                        - state
                        - data
                        - status_reason
                        - is_disabled
                  next_cursor:
                    type:
                      - string
                      - 'null'
                  total_pages:
                    type: number
                  current_page:
                    type: number
                  total_items:
                    type: number
                required:
                  - items
                  - total_pages
                  - current_page
                  - total_items
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: Your Composio user API key for user-scoped endpoints.
      x-default: your-user-api-key

````