---

List all Projects

The projectList query allows you to retrieve projects with powerful filtering, sorting, and pagination options.

Basic Example

query ProjectListQuery {
  projectList(filter: { companyIds: ["ENTER COMPANY ID"] }) {
    items {
      id
      uid
      slug
      name
      description
      archived
      color
      icon
      createdAt
      updatedAt
      allowNotification
      position
      unseenActivityCount
      todoListsMaxPosition
      lastAccessedAt
      isTemplate
      automationsCount
      totalFileCount
      totalFileSize
      todoAlias
    }
    pageInfo {
      totalPages
      totalItems
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

Advanced Example with Filtering and Sorting

query FilteredProjectList {
  projectList(
    filter: {
      companyIds: ["company-123", "company-456"]
      archived: false
      isTemplate: false
      search: "marketing"
      inProject: true
      folderId: null  # Get root-level projects only
    }
    sort: [position_ASC, name_ASC]
    skip: 0
    take: 50
  ) {
    items {
      id
      name
      slug
      position
      archived
    }
    totalCount
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Project Fields

The following table describes all available fields for each project in the ProjectListQuery:

Field	Type	Description
id	ID!	Unique identifier for the project
uid	String!	User-friendly unique identifier for the project
slug	String!	URL-friendly name of the project
name	String!	Display name of the project
description	String	Brief description of the project
archived	Boolean	Boolean indicating if the project is archived
color	String	Color associated with the project for visual identification
icon	String	Icon associated with the project for visual identification
image	Image	Project cover image object
createdAt	DateTime!	Timestamp when the project was created
updatedAt	DateTime!	Timestamp when the project was last updated
allowNotification	Boolean!	Boolean indicating if notifications are enabled for the project
position	Float!	Numeric value representing the project's position in a list
unseenActivityCount	Int!	Number of unseen activities in the project
todoListsMaxPosition	Float!	Maximum position value for todo lists in the project
lastAccessedAt	DateTime	Timestamp when the project was last accessed
isTemplate	Boolean!	Boolean indicating if the project is a template
isOfficialTemplate	Boolean!	Boolean indicating if this is an official Blue template
automationsCount(isActive: Boolean)	Int!	Number of automations associated with the project
totalFileCount	Int	Total number of files in the project
totalFileSize	Float	Total size of all files in the project (in bytes)
todoAlias	String	Custom alias for "todo" used in the project
category	ProjectCategory!	Project category (CRM, MARKETING, etc.)
hideEmailFromRoles	[UserAccessLevel!]	Array of roles that should hide email addresses
hideStatusUpdate	Boolean	Boolean for hiding status updates
company	Company!	Full company object details
accessLevel(userId: String)	UserAccessLevel	Get user's access level for the specific project
folder	Folder	Folder containing this project
features	[ProjectFeature!]	Array of enabled project features
sequenceCustomField	CustomField	Custom field used for sequence numbering
coverConfig	TodoCoverConfig	Configuration for todo cover images
hideRecordCount	Boolean	Whether to hide record counts
showTimeSpentInTodoList	Boolean	Whether to show time spent in todo lists
showTimeSpentInProject	Boolean	Whether to show time spent in project
todoFields	[TodoField]	Custom todo field definitions

Note: You can request any combination of these fields in your GraphQL query.

Pagination Fields

The pageInfo object provides pagination details for the query results:

Field	Type	Description
totalPages	Int	Total number of pages of results
totalItems	Int	Total number of projects matching the query
page	Int	Current page number
perPage	Int	Number of items per page
hasNextPage	Boolean!	Boolean indicating if there's a next page of results
hasPreviousPage	Boolean!	Boolean indicating if there's a previous page of results

Query Parameters

Filter Options (ProjectListFilter)

Parameter	Type	Required	Description
companyIds	[String!]!	✅ Yes	Array of company IDs or slugs to search within
ids	[String!]	No	Filter by specific project IDs
archived	Boolean	No	Filter by archived status (true/false)
isTemplate	Boolean	No	Filter template projects (true/false)
search	String	No	Search projects by name (case-insensitive)
folderId	String	No	Filter by folder ID. Use null for root-level projects
inProject	Boolean	No	Filter by user membership. See note below

Note on inProject filter:

• true or undefined: Returns projects the user is a member of
• false: Returns projects the user is NOT in (requires company owner permission)
• Folder filtering (folderId) only works when inProject is not false

Sorting Options (ProjectSort)

Value	Description
id_ASC	Sort by ID ascending
id_DESC	Sort by ID descending
name_ASC	Sort by name ascending (A-Z)
name_DESC	Sort by name descending (Z-A)
createdAt_ASC	Sort by creation date (oldest first)
createdAt_DESC	Sort by creation date (newest first)
updatedAt_ASC	Sort by last update (oldest first)
updatedAt_DESC	Sort by last update (newest first)
position_ASC	Sort by position ascending*
position_DESC	Sort by position descending*

*Position sorting is only available when viewing projects the user is a member of (inProject !== false)

Pagination Parameters

Parameter	Type	Default	Description
skip	Int	0	Number of records to skip
take	Int	20	Number of records to return

Important Notes

1. Default behavior for non-member projects (inProject: false):

   • Excludes archived projects unless archived filter is explicitly set
   • Excludes template projects unless isTemplate filter is explicitly set

2. Folder filtering limitations:

   • Only works when showing user's projects
   • Cannot be used with inProject: false
   • Use folderId: null to get projects not in any folder

3. Sorting fallback:

   • Position sorting is ignored when viewing non-member projects
   • Falls back to name sorting in such cases

4. Deprecated parameters:

   • orderBy, after, before, first, last are deprecated
   • Use sort, skip, and take instead