Query and filter records (todos) in Blue with powerful search and pagination options.
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
andlimit
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