# 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`

### 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
    - `status_reason` (string,null) *(required)*: The reason the connection 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": {},
      "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"
```