> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apps.filed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get workspace connections

> List provider connections for a workspace with their status

Query the list of provider connections for a workspace. This allows you to see all integrations configured for a workspace and their current connection status.

```graphql theme={null}
query GetWorkspaceConnections($workspaceId: ID!, $filters: ConnectionFilters, $limit: Int, $offset: Int, $sortBy: SortBy) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections(filters: $filters, limit: $limit, offset: $offset, sortBy: $sortBy) {
        id
        providerKey
        status
        provider {
          category
        }
      }
    }
  }
}
```

<Info>
  **Query Pattern**: Connections are accessed through the `Workspace` type. Query workspaces, then access the `connections` field to get all provider connections.
</Info>

## Arguments

<ParamField path="workspaceId" type="ID!" required>
  The ID of the workspace to query connections for.
</ParamField>

<ParamField path="filters" type="ConnectionFilters">
  Optional filters to narrow down the connections returned.

  <Expandable title="ConnectionFilters properties">
    <ParamField path="ids" type="[ID!]">
      Filter by specific connection IDs.
    </ParamField>

    <ParamField path="statuses" type="[String!]">
      Filter by connection status (e.g., `active`, `pending`, `failed`).
    </ParamField>

    <ParamField path="providerKeys" type="[String!]">
      Filter by provider keys (e.g., `canopy`, `taxdome`, `karbon`).
    </ParamField>

    <ParamField path="categories" type="[String!]">
      Filter by provider categories.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="limit" type="Int">
  Maximum number of connections to return.
</ParamField>

<ParamField path="offset" type="Int">
  Number of connections to skip for pagination.
</ParamField>

<ParamField path="sortBy" type="SortBy">
  Optional sorting configuration.

  <Expandable title="SortBy properties">
    <ParamField path="field" type="String!">
      Field to sort by (e.g., `createdAt`, `updatedAt`, `status`).
    </ParamField>

    <ParamField path="order" type="SortByOrder!">
      Sort order: `ASC` for ascending, `DESC` for descending.
    </ParamField>
  </Expandable>
</ParamField>

## Returns

<ResponseField name="id" type="ID!">
  Unique identifier for the connection.
</ResponseField>

<ResponseField name="providerKey" type="String!">
  The provider key identifying the integration type (e.g., `canopy`, `taxdome`, `karbon`, `google_drive`, `sharepoint`).
</ResponseField>

<ResponseField name="status" type="String!">
  Current status of the connection. Common values include:

  * `active` - Connection is working and authenticated
  * `pending` - Connection setup is in progress
  * `failed` - Connection has failed or credentials are invalid
  * `disconnected` - Connection has been disconnected
</ResponseField>

<ResponseField name="provider.category" type="String!">
  The category of the provider. Common values include:

  * `practice_management` - Practice management systems (e.g., Canopy, TaxDome, Karbon)
  * `document_management` - Document storage providers (e.g., Google Drive, SharePoint)
  * `tax_software` - Tax preparation software (e.g., Drake, UltraTax, Lacerte)
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://gateway.filed.com/graphql \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <accessToken>" \
    -d '{
      "query": "query GetWorkspaceConnections($workspaceId: ID!, $filters: ConnectionFilters) { me { workspaces(filters: { ids: [$workspaceId] }) { id connections(filters: $filters) { id providerKey status provider { category } } } } }",
      "variables": {
        "workspaceId": "workspace_123456",
        "filters": {
          "statuses": ["active"]
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "me": {
        "workspaces": [
          {
            "id": "workspace_123456",
            "connections": [
              {
                "id": "conn_abc123",
                "providerKey": "canopy",
                "status": "active",
                "provider": {
                  "category": "practice_management"
                }
              },
              {
                "id": "conn_def456",
                "providerKey": "google_drive",
                "status": "active",
                "provider": {
                  "category": "document_management"
                }
              },
              {
                "id": "conn_ghi789",
                "providerKey": "taxdome",
                "status": "pending",
                "provider": {
                  "category": "practice_management"
                }
              }
            ]
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Additional Fields

The `ProviderConnection` type includes additional fields you can query:

```graphql theme={null}
query GetWorkspaceConnectionsDetailed($workspaceId: ID!) {
  me {
    workspaces(filters: { ids: [$workspaceId] }) {
      id
      connections {
        id
        providerKey
        status
        displayName
        createdAt
        updatedAt
        provider {
          name
          category
        }
      }
    }
  }
}
```

<ResponseField name="displayName" type="String">
  Human-readable name for the connection.
</ResponseField>

<ResponseField name="createdAt" type="Date!">
  Timestamp when the connection was created.
</ResponseField>

<ResponseField name="updatedAt" type="Date!">
  Timestamp when the connection was last updated.
</ResponseField>

<ResponseField name="provider" type="Provider!">
  Provider details including name and category.
</ResponseField>

## Troubleshooting

**Problem**: No connections returned or empty list

**Solutions**:

* Verify the workspace ID is correct
* Check that connections have been set up for this workspace
* Review filters to ensure they aren't excluding all connections

**Problem**: Connection shows `failed` status

**Solutions**:

* The connection credentials may have expired or been revoked
* Re-authenticate the connection using [start provider connection](/legacy/apis/endpoint/start-provider-connection)
* Check the provider's settings or permissions

<Note>
  To set up a new connection, use [start provider connection](/legacy/apis/endpoint/start-provider-connection). To complete authentication, use [collect provider connection](/legacy/apis/endpoint/collect-provider-connection).
</Note>