# List connected accounts with optional filters

**Documentation:** /reference/api-reference/connected-accounts/getConnectedAccounts

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.

---

## GET `/api/v3/connected_accounts`

**Endpoint:** `https://backend.composio.dev/api/v3/connected_accounts`

**Summary:** 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.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Query Parameters

- `toolkit_slugs` (array,null): The toolkit slugs of the connected accounts
- `statuses` (array,null): The status of the connected account
- `cursor` (string,null): The cursor to paginate through the connected accounts
- `limit` (number,null): The limit of the connected accounts to return
- `user_ids` (array,null): The user ids of the connected accounts
- `auth_config_ids` (array,null): The auth config ids of the connected accounts
- `connected_account_ids` (array,null): The connected account ids to filter by
- `order_by` (enum: "created_at" | "updated_at"): The order by of the connected accounts
- `order_direction` (enum: "asc" | "desc"): The order direction of the connected accounts

### Responses

#### 200 - Successfully retrieved connected accounts

**Response Schema:**

- `items` (array<object>) *(required)*
  - Array items:
    - `toolkit` (object) *(required)*
      - `slug` (string) *(required)*: The slug of the toolkit
    - `auth_config` (object) *(required)*
      - `id` (string (authConfigId)) *(required)*: The id of the auth config
      - `auth_scheme` (enum: "OAUTH2" | "OAUTH1" | "API_KEY" | ...) *(required)*: the authScheme is part of the connection state use it there
      - `is_composio_managed` (boolean) *(required)*: Whether the auth config is managed by Composio
      - `is_disabled` (boolean) *(required)*: Whether the auth config is disabled
      - `deprecated` (object)
        - `uuid` (string (uuid)) *(required)*: The uuid of the auth config
    - `id` (string (connectedAccountId)) *(required)*: The id of the connection
    - `user_id` (string) *(required)*: 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
    - `status` (enum: "INITIALIZING" | "INITIATED" | "ACTIVE" | ...) *(required)*: The status of the connection
    - `created_at` (string) *(required)*: The created at of the connection
    - `updated_at` (string) *(required)*: The updated at of the connection
    - `state` (object) *(required)*: The state of the connection
      - `authScheme` (enum: "OAUTH1" | "OAUTH2" | "API_KEY" | ...) *(required)*
      - `val` (object) *(required)*
        - `subdomain` (string)
        - `your-domain` (string)
        - `region` (string)
        - `shop` (string)
        - `account_url` (string)
        - `COMPANYDOMAIN` (string)
        - `extension` (string)
        - `form_api_base_url` (string)
        - `instanceEndpoint` (string)
        - `api_url` (string)
        - `borneo_dashboard_url` (string)
        - `proxy_username` (string)
        - `proxy_password` (string)
        - `domain` (string)
        - `version` (string)
        - `dc` (string)
        - `site_name` (string)
        - `instanceName` (string)
        - `account_id` (string)
        - `your_server` (string)
        - `server_location` (string)
        - `base_url` (string)
        - `status` (enum: "INITIALIZING" | "INITIATED" | "ACTIVE" | ...) *(required)*
        - `oauth_token` (string)
        - `authUri` (string)
        - `oauth_token_secret` (string)
        - `redirectUrl` (string)
        - `callbackUrl` (string)
        - `oauth_verifier` (string)
        - `consumer_key` (string)
        - `callback_url` (string)
        - `error` (string)
        - `error_description` (string)
        - `expired_at` (string)
    - `data` (object) *(required)*: This is deprecated, use `state` instead
      - `[key: string]` (any)
    - `status_reason` (string,null) *(required)*: The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled
    - `is_disabled` (boolean) *(required)*: Whether the connection is disabled
    - `test_request_endpoint` (string): The endpoint to make test request for verification
    - `deprecated` (object)
      - `labels` (array<string>) *(required)*: The labels of the connection
      - `uuid` (string (uuid)) *(required)*: The uuid of the connection
- `next_cursor` (string,null)
- `total_pages` (number) *(required)*
- `current_page` (number) *(required)*
- `total_items` (number) *(required)*

**Example Response:**

```json
{
  "items": [
    {
      "toolkit": {
        "slug": "..."
      },
      "auth_config": {
        "id": "...",
        "auth_scheme": "...",
        "is_composio_managed": "...",
        "is_disabled": "...",
        "deprecated": "..."
      },
      "id": "string",
      "user_id": "string",
      "status": "INITIALIZING",
      "created_at": "string",
      "updated_at": "string",
      "state": {
        "authScheme": "...",
        "val": "..."
      },
      "data": {
        "key": "..."
      },
      "status_reason": null,
      "is_disabled": true,
      "test_request_endpoint": "string",
      "deprecated": {
        "labels": "...",
        "uuid": "..."
      }
    }
  ],
  "next_cursor": null,
  "total_pages": 1,
  "current_page": 1,
  "total_items": 1
}
```

#### 400 - Bad request

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 422 - Unprocessable entity

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X GET "https://backend.composio.dev/api/v3/connected_accounts" \
  -H "x-api-key: YOUR_API_KEY"
```