List Records

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

Query Parameters

TodosSort Values

FilterLogicalOperator Values

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

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

PageInfo

Todo Fields

Required Permissions

Users must have appropriate access to query records:

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