Skip to content

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

Sushmithamallesh9966bb33d9bc
diff --git a/fern/pages/src/tool-calling/authenticating-tools.mdx b/fern/pages/src/tool-calling/authenticating-tools.mdx
index 676049570..4eff1a617 100644
--- a/fern/pages/src/tool-calling/authenticating-tools.mdx
+++ b/fern/pages/src/tool-calling/authenticating-tools.mdx
@@ -355,6 +355,42 @@ Composio also supports a wide range of other auth schemas:
successfully creating connections.
</Note>
+## Connection Statuses
+
+After creating a connection, it will have one of the following statuses that indicates its current state:
+
+| Status | Description |
+|--------|-------------|
+| **ACTIVE** | Connection is established and working. You can execute tools with this connection. |
+| **INACTIVE** | Connection is temporarily disabled. Re-enable it to use the connection again. |
+| **PENDING** | Connection is being processed. Wait for it to become active. |
+| **INITIATED** | Connection request has started but not yet completed. User may still need to complete authentication. |
+| **EXPIRED** | Connection credentials have expired. Re-authenticate to restore access. |
+| **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |
+
+### Checking Connection Status
+
+You can check the status of a connected account programmatically:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/tool-calling/python/checking-connection-status.py"
+ title="Python"
+ startLine={5}
+ endLine={15}
+/>
+<SnippetCode
+ src="fern/snippets/tool-calling/typescript/checking-connection-status.ts"
+ title="Typescript"
+ startLine={5}
+ endLine={16}
+/>
+</CodeGroup>
+
+<Note>
+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.
+</Note>
+
## Next Step
With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.
diff --git a/fern/snippets/tool-calling/python/checking-connection-status.py b/fern/snippets/tool-calling/python/checking-connection-status.py
new file mode 100644
index 000000000..192752eed
--- /dev/null
+++ b/fern/snippets/tool-calling/python/checking-connection-status.py
@@ -0,0 +1,15 @@
+from composio import Composio
+
+composio = Composio(api_key="your_api_key")
+
+# Get a specific connected account
+connected_account = composio.connected_accounts.get("your_connected_account_id")
+print(f"Status: {connected_account.status}")
+
+# Filter connections by user_id and auth_config_id
+filtered_connections = composio.connected_accounts.list(
+ user_ids=["user_123"],
+ auth_config_ids=["your_auth_config_id"]
+)
+for connection in filtered_connections.items:
+ print(f"{connection.id}: {connection.status}")
diff --git a/fern/snippets/tool-calling/typescript/checking-connection-status.ts b/fern/snippets/tool-calling/typescript/checking-connection-status.ts
new file mode 100644
index 000000000..d78ddb606
--- /dev/null
+++ b/fern/snippets/tool-calling/typescript/checking-connection-status.ts
@@ -0,0 +1,16 @@
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your_api_key' });
+
+// Get a specific connected account by its nanoid
+const connectedAccount = await composio.connectedAccounts.get('your_connected_account_id');
+console.log(`Status: ${connectedAccount.status}`);
+
+// Filter connections by user_id and auth_config_id
+const filteredConnections = await composio.connectedAccounts.list({
+ userIds: ['user_123'],
+ authConfigIds: ['your_auth_config_id']
+});
+filteredConnections.items.forEach(connection => {
+ console.log(`${connection.id}: ${connection.status}`);
+});