> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# List connected accounts

`GET /api/v1/connected_accounts`

Lists the connected accounts in the environment, filtered by connection, identifier, provider or organization, with each account's status. The list doesn't include credentials; use [Get a connected account's credentials](https://docs.scalekit.com/agentkit/reference/connected-accounts/get-connected-account-credentials/) for one account. Use `next_page_token` to get the next page.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_names` | array of string | No | Filter by one or more connection names (exact match). Returns connected accounts belonging to any of the specified connections. Max 20 names per request. Cannot be combined with the `connector` field. |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `is_org_wide_credential` | boolean | No | Set to `true` to return only the shared credential of an org-wide connection, or `false` to return only users' own accounts. Omit it to return both. |
| `organization_id` | string | No | Filter by organization ID. Returns only connected accounts associated with this organization. |
| `page_size` | integer | No | Maximum number of connected accounts to return, up to 99. Defaults to 10 when omitted or 0. |
| `page_token` | string | No | Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page. |
| `provider` | string | No | Return only accounts for this app, such as `GMAIL` or `SLACK`. Exact match, in capitals as the account's `provider` shows it. |
| `query` | string | No | Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive. |
| `user_id` | string | No | Filter by user ID. Returns only connected accounts associated with this user. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_accounts` | array of object | List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. |
| `connected_accounts.authorization_type` | string (enum) | Authorization mechanism type. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_accounts.connection_id` | string | Parent connection configuration reference. |
| `connected_accounts.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_accounts.id` | string | Unique connected account identifier. |
| `connected_accounts.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_accounts.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_accounts.last_used_at` | string | Last usage timestamp. |
| `connected_accounts.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_accounts.status` | string (enum) | Current connection status. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_accounts.token_expires_at` | string | Token expiration timestamp. |
| `connected_accounts.updated_at` | string | Last modification timestamp. |
| `next_page_token` | string | Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page_token in the next request. |
| `prev_page_token` | string | Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page_token to go back. |
| `total_size` | integer | Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. |

**Errors**

- `400`: Invalid request - occurs when query parameters are malformed or validation fails
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "connector=gmail" \
  --data-urlencode "identifier=user_123"
```

**Response**

```json
{
  "connected_accounts": [
    {
      "id": "ca_24834495392086178",
      "connection_id": "conn_70219645518265104",
      "connector": "gmail",
      "identifier": "user_123",
      "provider": "GMAIL",
      "authorization_type": "OAUTH",
      "status": "ACTIVE",
      "is_org_wide_credential": false,
      "token_expires_at": "2026-10-02T15:30:00Z",
      "last_used_at": "2026-10-02T14:31:07Z",
      "updated_at": "2026-10-02T14:30:00Z"
    }
  ],
  "next_page_token": "",
  "prev_page_token": "",
  "total_size": 1
}
```

**Python SDK:** `scalekit_client.actions.list_connected_accounts`

List connected accounts with optional filtering.

```python
scalekit_client.actions.list_connected_accounts(
    connection_name: Optional[str] = None,
    identifier: Optional[str] = None,
    provider: Optional[str] = None,
    connection_names: Optional[List[str]] = None,
) -> ListConnectedAccountsResponse
```

Example:

```python
result = scalekit_client.actions.list_connected_accounts(
    connection_name="gmail",
    identifier="user_123",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `provider` | `Optional[str]` | No | Return only accounts for this app, such as `GMAIL` or `SLACK`. Exact match, in capitals as the account's `provider` shows it. |
| `connection_names` | `Optional[List[str]]` | No | Connection names, exact match. Returns accounts on any of them, such as `["gmail", "github-connect"]`. Combine with `identifier` for one user. |

Returns `ListConnectedAccountsResponse`: The matching connected accounts.

**Node.js SDK:** `scalekit.actions.listConnectedAccounts`

List connected accounts with optional filters.

```ts
scalekit.actions.listConnectedAccounts(
  params?: {
    connectionName?: string;
    identifier?: string;
    provider?: string;
    organizationId?: string;
    userId?: string;
    pageSize?: number;
    pageToken?: string;
    query?: string;
    connectionNames?: string[];
  },
): Promise<ListConnectedAccountsResponse>
```

Example:

```ts
const result = await scalekit.actions.listConnectedAccounts({
  connectionName: "gmail",
  identifier: "user_123",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `provider` | `string` | No | Return only accounts for this app, such as `GMAIL` or `SLACK`. Exact match, in capitals as the account's `provider` shows it. |
| `organizationId` | `string` | No | Filter by organization ID. Returns only connected accounts associated with this organization. |
| `userId` | `string` | No | Filter by user ID. Returns only connected accounts associated with this user. |
| `pageSize` | `number` | No | Maximum number of connected accounts to return, up to 99. Defaults to 10 when omitted or 0. |
| `pageToken` | `string` | No | Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page. |
| `query` | `string` | No | Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive. |
| `connectionNames` | `string[]` | No | Filter by one or more connection names (exact match). Returns connected accounts belonging to any of the specified connections. Max 20 names per request. Cannot be combined with the `connector` field. |

Returns `Promise<ListConnectedAccountsResponse>`.

**Used in**

- [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/)


Part of [Connected accounts](https://docs.scalekit.com/agentkit/reference/connected-accounts/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |