@devries-cameron20 / composio-1 / commits / 9966bb33d
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Add connected account status docs

Sushmithamallesh committed Nov 4, 2025 at 12:30 UTC 9966bb33d9bcfdc8ab4e2f7ffc33222357a02dd1
3 files changed +67
fern/pages/src/tool-calling/authenticating-tools.mdx
+36
@@ -355,6 +355,42 @@ Composio also supports a wide range of other auth schemas:
355 successfully creating connections.
356 </Note>
357
358 +## Connection Statuses
359 +
360 +After creating a connection, it will have one of the following statuses that indicates its current state:
361 +
362 +| Status | Description |
363 +|--------|-------------|
364 +| **ACTIVE** | Connection is established and working. You can execute tools with this connection. |
365 +| **INACTIVE** | Connection is temporarily disabled. Re-enable it to use the connection again. |
366 +| **PENDING** | Connection is being processed. Wait for it to become active. |
367 +| **INITIATED** | Connection request has started but not yet completed. User may still need to complete authentication. |
368 +| **EXPIRED** | Connection credentials have expired. Re-authenticate to restore access. |
369 +| **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |
370 +
371 +### Checking Connection Status
372 +
373 +You can check the status of a connected account programmatically:
374 +
375 +<CodeGroup>
376 +<SnippetCode
377 + src="fern/snippets/tool-calling/python/checking-connection-status.py"
378 + title="Python"
379 + startLine={5}
380 + endLine={15}
381 +/>
382 +<SnippetCode
383 + src="fern/snippets/tool-calling/typescript/checking-connection-status.ts"
384 + title="Typescript"
385 + startLine={5}
386 + endLine={16}
387 +/>
388 +</CodeGroup>
389 +
390 +<Note>
391 +Only connections with **ACTIVE** status can be used to execute tools. If a connection is in any other state, you'll need to take appropriate action (re-authenticate, wait for processing, etc.) before using it.
392 +</Note>
393 +
394 ## Next Step
395
396 With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.
fern/snippets/tool-calling/python/checking-connection-status.py new
+15
@@ -0,0 +1,15 @@
1 +from composio import Composio
2 +
3 +composio = Composio(api_key="your_api_key")
4 +
5 +# Get a specific connected account
6 +connected_account = composio.connected_accounts.get("your_connected_account_id")
7 +print(f"Status: {connected_account.status}")
8 +
9 +# Filter connections by user_id and auth_config_id
10 +filtered_connections = composio.connected_accounts.list(
11 + user_ids=["user_123"],
12 + auth_config_ids=["your_auth_config_id"]
13 +)
14 +for connection in filtered_connections.items:
15 + print(f"{connection.id}: {connection.status}")
fern/snippets/tool-calling/typescript/checking-connection-status.ts new
+16
@@ -0,0 +1,16 @@
1 +import { Composio } from '@composio/core';
2 +
3 +const composio = new Composio({ apiKey: 'your_api_key' });
4 +
5 +// Get a specific connected account by its nanoid
6 +const connectedAccount = await composio.connectedAccounts.get('your_connected_account_id');
7 +console.log(`Status: ${connectedAccount.status}`);
8 +
9 +// Filter connections by user_id and auth_config_id
10 +const filteredConnections = await composio.connectedAccounts.list({
11 + userIds: ['user_123'],
12 + authConfigIds: ['your_auth_config_id']
13 +});
14 +filteredConnections.items.forEach(connection => {
15 + console.log(`${connection.id}: ${connection.status}`);
16 +});