List Workspaces

Use the workspaceList query to retrieve the workspaces in one or more organizations, with filtering, sorting, and pagination. Workspaces are Workspace objects in the API, and an organization is an Organization. By default workspaceList returns the workspaces the authenticated user is a member of; organization owners can also list workspaces they are not in (see Permissions).

Request

The smallest call passes the organizations to search in via the required companyIds filter. Each entry is an organization ID or slug.

query ListWorkspaces {
  workspaceList(filter: { companyIds: ["company_123"] }) {
    items {
      id
      name
      slug
      archived
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Parameters

workspaceList takes a required filter, plus optional sort, skip, and take.

ProjectListFilter

inProject membership scope

• true or omitted: return workspaces the authenticated user is a member of.
• false: return workspaces the user is not a member of. Requires the user to be an owner of at least one of the supplied organizations, otherwise the query throws FORBIDDEN.

ProjectSort

Response

workspaceList returns a ProjectPagination: the matched workspaces in items, page metadata in pageInfo, and the total match count in totalCount (a sibling of pageInfo, not a field inside it).

{
  "data": {
    "workspaceList": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "name": "Marketing Campaigns",
          "slug": "marketing-campaigns",
          "archived": false
        },
        {
          "id": "clm4n9b2y000108l0a1b2c3d4",
          "name": "Product Roadmap",
          "slug": "product-roadmap",
          "archived": false
        }
      ],
      "pageInfo": {
        "totalItems": 2,
        "hasNextPage": false
      }
    }
  }
}

ProjectPagination

PageInfo

Workspace fields

Each entry in items is a Workspace. Commonly requested fields are below; request any combination your integration needs.

Full example

This call lists active, non-template workspaces in two organizations whose names contain “marketing”, sorted by manual position then name, and reads the first 50 plus the total count.

query FilteredWorkspaces {
  workspaceList(
    filter: {
      companyIds: ["company_123", "acme-corp"]
      archived: false
      isTemplate: false
      search: "marketing"
      inProject: true
      folderId: null # root-level workspaces only (not in any folder)
    }
    sort: [position_ASC, name_ASC]
    skip: 0
    take: 50
  ) {
    items {
      id
      name
      slug
      position
      archived
      category
      unseenActivityCount
      automationsCount(isActive: true)
      organization {
        id
        name
      }
    }
    totalCount
    pageInfo {
      totalItems
      totalPages
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

Behavior notes

• Folder filtering requires membership. folderId is only valid when listing the user’s own workspaces (inProject omitted or true). Combining folderId (including folderId: null) with inProject: false returns an error, because the user has no folder placement for workspaces they don’t belong to.
• Position sort needs membership. position_ASC / position_DESC reflect the user’s manual ordering. When inProject: false, position sorting falls back to sorting by name.
• Non-member defaults. With inProject: false, archived and template workspaces are excluded unless you set archived or isTemplate explicitly.

Errors

Permissions

By default workspaceList returns only workspaces the authenticated user belongs to within the given organizations. Listing workspaces the user is not in (inProject: false) requires the user to be an owner of at least one of the organizations in companyIds.

Related

• Create a workspace
• Rename a workspace
• Archive a workspace
• Lists
• List records