---

List Records

The todos query allows you to retrieve records from Blue with comprehensive filtering, sorting, and pagination options. You can query records across companies, projects, or filter by specific criteria like assignees, tags, and dates.

Basic Example

List all records in a company with minimal parameters:

query ListRecords {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
      }
    ) {
      items {
        id
        title
        done
        duedAt
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Advanced Example

Query records with comprehensive filtering, sorting, and field selection:

query ListRecordsAdvanced {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_456", "project_789"]
        assigneeIds: ["user_123"]
        tagIds: ["tag_priority", "tag_urgent"]
        showCompleted: false
        dueStart: "2025-01-01T00:00:00Z"
        dueEnd: "2025-12-31T23:59:59Z"
        search: "product launch"
        excludeArchivedProjects: true
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "cf_status_123"
            customFieldType: "SELECT_SINGLE"
            values: ["In Progress", "Review"]
            op: "IN"
          }
        ]
        op: "AND"
      }
      sort: [duedAt_ASC, position_ASC]
      limit: 50
      skip: 0
    ) {
      items {
        id
        uid
        position
        title
        text
        html
        startedAt
        duedAt
        timezone
        color
        cover
        done
        archived
        createdAt
        updatedAt
        commentCount
        checklistCount
        checklistCompletedCount
        isRepeating
        todoList {
          id
          title
        }
        users {
          id
          name
          email
        }
        tags {
          id
          title
          color
        }
        customFields {
          id
          title
          type
          value
        }
        createdBy {
          id
          name
        }
      }
      pageInfo {
        totalPages
        totalItems
        page
        perPage
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Input Parameters

TodosFilter

Parameter	Type	Required	Description
companyIds	[String!]!	✅ Yes	Company IDs or slugs to query from
projectIds	[String!]	No	Filter by specific project IDs or slugs
todoIds	[String!]	No	Retrieve specific todos by their IDs
assigneeIds	[String!]	No	Filter by assigned user IDs
tagIds	[String!]	No	Filter by tag IDs
tagColors	[String!]	No	Filter by tag colors (hex format)
tagTitles	[String!]	No	Filter by tag titles
todoListIds	[String!]	No	Filter by todo list IDs
todoListTitles	[String!]	No	Filter by todo list titles
done	Boolean	No	Filter by completion status (deprecated, use showCompleted)
showCompleted	Boolean	No	Show/hide completed todos (default: true)
startedAt	DateTime	No	Filter by start date
duedAt	DateTime	No	Filter by exact due date
dueStart	DateTime	No	Due date range start (inclusive)
dueEnd	DateTime	No	Due date range end (inclusive)
search	String	No	Search in title and text content
q	String	No	Alternative search parameter (same as search)
excludeArchivedProjects	Boolean	No	Exclude todos from archived projects
coordinates	JSON	No	Geo-spatial filter for map view (polygon coordinates)
fields	JSON	No	Custom field filters (see advanced filtering)
op	FilterLogicalOperator	No	Logical operator for field filters (AND/OR)

Query Parameters

Parameter	Type	Required	Description
filter	TodosFilter!	✅ Yes	Filter criteria for the query
sort	[TodosSort!]	No	Sort order (default: empty array)
limit	Int	No	Number of items per page (default: 20, max: 500)
skip	Int	No	Number of items to skip for pagination (default: 0)

TodosSort Values

Value	Description
assignees_ASC	Sort by assignee names ascending
assignees_DESC	Sort by assignee names descending
createdAt_ASC	Sort by creation date ascending (oldest first)
createdAt_DESC	Sort by creation date descending (newest first)
createdBy_ASC	Sort by creator name ascending
createdBy_DESC	Sort by creator name descending
duedAt_ASC	Sort by due date ascending (earliest first)
duedAt_DESC	Sort by due date descending (latest first)
position_ASC	Sort by position ascending (default list order)
position_DESC	Sort by position descending
startedAt_ASC	Sort by start date ascending
startedAt_DESC	Sort by start date descending
title_ASC	Sort by title alphabetically ascending
title_DESC	Sort by title alphabetically descending
todoListPosition_ASC	Sort by todo list position ascending
todoListPosition_DESC	Sort by todo list position descending
todoListTitle_ASC	Sort by todo list title ascending
todoListTitle_DESC	Sort by todo list title descending
todoTags_ASC	Sort by tags ascending
todoTags_DESC	Sort by tags descending

FilterLogicalOperator Values

Value	Description
AND	All conditions must match
OR	Any condition must match

Custom Field Filtering

The fields parameter supports advanced filtering by custom fields:

{
  "fields": [
    {
      "type": "CUSTOM_FIELD",
      "customFieldId": "cf_123",
      "customFieldType": "SELECT_SINGLE",
      "values": ["Option1", "Option2"],
      "op": "IN"
    }
  ]
}

Custom Field Filter Structure

Field	Type	Description
type	String	Must be "CUSTOM_FIELD"
customFieldId	String	ID of the custom field
customFieldType	String	Type of the custom field
values	[String!]	Values to filter by
op	String	Comparison operator (IN, NOT_IN, EQ, etc.)

Supported Custom Field Types

• Text fields: TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID
• Numeric fields: CURRENCY, NUMBER, FORMULA
• Selection fields: SELECT_SINGLE, SELECT_MULTI, CHECKBOX, COUNTRY
• Reference fields: REFERENCE, LOOKUP
• Date fields: DATE

Response Fields

TodosResult

Field	Type	Description
items	[Todo!]!	Array of todo records
pageInfo	PageInfo!	Pagination metadata

PageInfo

Field	Type	Description
totalPages	Int	Total number of pages available
totalItems	Int	Total number of items across all pages
page	Int	Current page number (calculated from skip/limit)
perPage	Int	Number of items per page
hasNextPage	Boolean!	Whether there is a next page
hasPreviousPage	Boolean!	Whether there is a previous page

Todo Fields

Field	Type	Description
id	ID!	Unique identifier
uid	String!	User-friendly unique identifier
position	Float!	Position in the list
title	String!	Todo title
text	String!	Plain text content
html	String!	HTML formatted content
startedAt	DateTime	Start date/time
duedAt	DateTime	Due date/time
timezone	String	Timezone for dates
color	String	Visual color indicator
cover	String	Cover image URL
done	Boolean!	Completion status
archived	Boolean!	Archive status
createdAt	DateTime!	Creation timestamp
updatedAt	DateTime!	Last update timestamp
commentCount	Int!	Number of comments
checklistCount	Int!	Total checklist items
checklistCompletedCount	Int!	Completed checklist items
isRepeating	Boolean!	Whether todo is recurring
isRead	Boolean	Read status for current user
isSeen	Boolean	Seen status for current user
todoList	TodoList!	Parent todo list
users	[User!]!	Assigned users
tags	[Tag!]!	Associated tags
checklists	[Checklist!]!	Associated checklists
createdBy	User	User who created the todo
customFields	[CustomField!]!	Custom field values
dependOn	[Todo!]	Blocking todos (dependencies)
dependBy	[Todo!]	Dependent todos (blocked by this)
timeTracking	TimeTracking	Time tracking data

Required Permissions

Users must have appropriate access to query records:

Access Type	Requirements
Company Access	User must be a member of the company
Project Access	User must have access to specific projects (if filtering by project)
Todo Visibility	Depends on user's role and permissions:
- VIEW_ONLY	Can view all accessible todos
- COMMENT_ONLY	Can view all accessible todos
- CLIENT	May be restricted to assigned todos only
- MEMBER	Can view all project todos
- ADMIN	Can view all project todos
- OWNER	Can view all company todos

Special Restrictions:

• Users with showOnlyAssignedTodos permission can only see todos assigned to them
• Hidden todo lists (based on role configuration) are automatically excluded
• Tag-based permissions may further filter results

Error Responses

Common Errors

The query handles errors gracefully and returns empty results for:

• Invalid company IDs
• Inaccessible projects
• Permission denied scenarios

For severe errors, GraphQL errors may be returned:

{
  "errors": [{
    "message": "Query timeout exceeded",
    "extensions": {
      "code": "QUERY_TIMEOUT"
    }
  }]
}

Important Notes

Performance

• Default limit: 20 items per page (automatically applied if not specified)
• Maximum limit: 500 items per request (automatically capped)
• Optimization: Queries use optimized joins with STRAIGHT_JOIN for best performance
• Indexing: Common filter fields are indexed for fast querying
• Custom fields: Extensive custom field filtering support with minimal performance impact
• Geographic queries: Supports polygon-based coordinate filtering for map views

Date Filtering

• Date ranges are inclusive
• Supports overlapping date ranges (todos that start or end within the range)
• Null dates are handled gracefully (todos without due dates won't match date filters)
• All dates should be in ISO 8601 format

Search Behavior

• Search is case-insensitive
• Searches in both title and text content
• Partial word matching is supported
• Special characters are handled appropriately

Pagination Strategy

• Use skip and limit for offset-based pagination
• Calculate current page: page = Math.floor(skip / limit) + 1
• For large datasets, consider using filters to reduce result size
• Always check hasNextPage before incrementing skip

Related Endpoints

• Create Record: Use createTodo mutation to create new records
• Update Record: Use updateTodo mutation to modify records
• Delete Record: Use deleteTodo mutation to remove records
• List Custom Fields: Query available custom fields for filtering
• List Projects: Query available projects for filtering