List Records

Use the recordQueries.todos query to read records from Blue with filtering, sorting, and pagination. Records are Record objects in the API; in the app they appear as the cards inside a workspace’s lists. A single call can span one organization, several workspaces, or a precise slice defined by assignees, tags, dates, and custom-field conditions.

This is the only operation that filters records server-side. (In-app search filters client-side after records load, so it can’t reach records beyond what the client has fetched.)

Request

The query lives under the recordQueries namespace. The only required input is companyIds — one or more organization IDs or slugs.

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

The companyIds, projectIds, and todoListIds arrays each accept IDs or slugs.

Parameters

Arguments

TodosFilter

The flat fields below combine with AND by default. For mixed AND/OR logic and the full set of conditions (record-name match, completion-date range, last-updated-by actor), use groups instead — see Group filtering.

TodosSort

Each value is a field_DIRECTION enum member. Pass an array to sort by multiple keys in order.

Rank replaces position for manual order

rank is the manual-order key for records. The retired position_ASC and position_DESC values are no longer part of TodosSort.

Treat each rank as an opaque string. Compare ranks only between records in the same list. Do not parse a rank, generate one, or compare ranks from different lists. To place or move a record, send previousId and/or nextId; Blue allocates the new rank.

A rank sort must be the only sort and the filter must resolve to exactly one list. Use rank_DESC for the board’s top-to-bottom order. For queries that span lists, choose another sort field because each list has its own rank space.

FilterLogicalOperator

Response

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "title": "Draft Q3 launch plan",
            "done": false,
            "duedAt": "2026-07-15T17:00:00.000Z"
          },
          {
            "id": "clm4n8qwx000108l0haz1f2pe",
            "title": "Review pricing page copy",
            "done": true,
            "duedAt": null
          }
        ],
        "pageInfo": {
          "totalItems": 2,
          "hasNextPage": false
        }
      }
    }
  }
}

TodosResult

PageInfo

Record

The most useful fields on each returned record. The Record type exposes more — these are the ones you’ll select most often.

Full example

Filter to open, high-priority records in two workspaces, due in 2026, sorted by due date then list title, with a rich selection set.

query ListRecordsAdvanced {
  recordQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_123", "project_456"]
        assigneeIds: ["user_123"]
        tagIds: ["tag_123"]
        showCompleted: false
        dueStart: "2026-01-01T00:00:00Z"
        dueEnd: "2026-12-31T23:59:59Z"
        search: "launch"
        excludeArchivedProjects: true
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "field_123"
            customFieldType: "SELECT_SINGLE"
            op: "IN"
            values: ["option_123", "option_456"]
          }
        ]
        op: AND
      }
      sort: [duedAt_ASC, todoListTitle_ASC]
      limit: 50
      skip: 0
    ) {
      items {
        id
        uid
        title
        text
        duedAt
        done
        completedAt
        todoList {
          id
          title
        }
        users {
          id
          fullName
          email
        }
        tags {
          id
          title
          color
        }
        customFields {
          id
          name
          type
          value
          selectedOption {
            title
          }
        }
        createdBy {
          id
          fullName
        }
      }
      pageInfo {
        totalPages
        totalItems
        page
        perPage
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Archive scope

Archiving takes a record out of its list without deleting it (see Archive a record). The archived filter selects which side of that partition you read:

There is no value that returns active and archived records together in a single call — the filter is a partition, not an inclusion toggle, so each query reads one side or the other. To assemble a complete picture, run the query twice (once with archived: false or omitted, once with archived: true) and merge the two result sets client-side.

query ArchivedRecords {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], projectIds: ["project_123"], archived: true }) {
      items {
        id
        title
        archived
        archivedAt
      }
      pageInfo {
        totalItems
      }
    }
  }
}

List all records in a workspace

To read every record in one workspace, filter by that workspace and page through the results. companyIds is always required; add the workspace to projectIds and omit todoListIds so the query spans every list:

query AllWorkspaceRecords {
  recordQueries {
    todos(
      filter: { companyIds: ["company_123"], projectIds: ["project_123"] }
      limit: 500
      skip: 0
    ) {
      items {
        id
        title
        todoList {
          id
          title
        }
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

A few things to keep in mind:

• Paginate to completion. A page is capped at 500 (the limit ceiling). Increment skip by your page size until pageInfo.hasNextPage is false; pageInfo.totalItems gives you the full count up front so you can size the loop.
• This returns active records only. Archived records are excluded by default — see Archive scope. To include them, run the same query a second time with archived: true and combine the pages.
• One query covers the whole workspace. There’s no per-list call to make — a single query with no todoListIds returns records from every list in the workspace.
• Span workspaces or the whole org. projectIds accepts several IDs to cover multiple workspaces at once; drop projectIds entirely to read across every workspace in the organizations named in companyIds.
• Visibility still applies. Records the caller can’t see — restricted lists, assigned-only roles, tag-based rules — are filtered out silently rather than erroring.

Cursor pagination

Offset pagination (skip) is simple, but it gets more expensive the deeper you page — reaching row 100,000 still means the database walks past the 99,999 rows before it. For large single-list scans, filter.rankBefore provides a keyset cursor that seeks directly to the page boundary through an index, so page 100 costs the same as page 1.

rankBefore is opt-in and deliberately narrow. It is honored only when all of the following hold; violating any one returns a BAD_USER_INPUT error rather than silently falling back to offset mode:

• filter.todoListIds names exactly one list.
• sort is exactly one of [rank_ASC] or [rank_DESC].
• rankBefore is not combined with skip.

To start a chain, run the first page with sort and todoListIds set and no rankBefore. Select rankPage { status generation } alongside items. Take the last item’s rank and id, plus that generation, and pass all three back as rankBefore on the next request. Keep going until a page returns fewer items than limit.

generation guards against a rank rebalance landing mid-scan. If the list’s ranks are rewritten between pages, the server returns an empty page with rankPage.status: RESET_REQUIRED and the new generation, instead of silently skipping or repeating records. Restart the chain from page 1 when you see that.

query RankPage {
  recordQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        todoListIds: ["list_123"]
        rankBefore: { rank: "a0V", id: "record_456", generation: 3 }
      }
      sort: [rank_DESC]
      limit: 100
    ) {
      items {
        id
        title
        rank
      }
      rankPage {
        status
        generation
      }
    }
  }
}

Custom-field filtering

TodosFilter.fields is typed JSON. Each entry must include a type discriminator — entries without one are silently dropped. The query layer routes on type:

A CUSTOM_FIELD entry has this shape:

{
  "type": "CUSTOM_FIELD",
  "customFieldId": "field_123",
  "customFieldType": "SELECT_SINGLE",
  "op": "IN",
  "values": ["option_123", "option_456"]
}

Filterable custom-field types

customFieldType must be a CustomFieldType enum value. These types can be filtered:

TEXT_SINGLE, TEXT_MULTI, URL, EMAIL, PHONE, UNIQUE_ID (text matching), NUMBER, CURRENCY, PERCENT, RATING, FORMULA (numeric comparison), CHECKBOX (IS true / IS false), SELECT_SINGLE, SELECT_MULTI (option matching), COUNTRY, DATE, ASSIGNEE, REFERENCE, LOOKUP, and ROLLUP.

The remaining CustomFieldType values are not filterable: LOCATION, FILE, TIME_DURATION, BUTTON, CURRENCY_CONVERSION, and REFERENCED_BY.

Group filtering

For mixed AND/OR logic, supply groups. When groups is present, the flat TodosFilter fields are ignored. Each group is a TodoFilterGroupInput with its own internal operator (op), and adjacent groups are linked by groupLinks.

query ListRecordsByGroups {
  recordQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        groups: [
          { op: AND, tagIds: ["tag_123"], showCompleted: false }
          { op: OR, recordName: "launch", recordNameOp: CONTAINS }
        ]
        groupLinks: [AND]
      }
      limit: 50
    ) {
      items {
        id
        title
      }
      pageInfo {
        totalItems
      }
    }
  }
}

TodoFilterGroupInput accepts the same assignee/tag/list/date/existence fields as the flat filter, plus group-only conditions:

The three lastUpdatedBy* axes compose with OR — a record matches if it satisfies any supplied axis. fields works exactly as in Custom-field filtering.

Errors

This query degrades gracefully: an inaccessible workspace or a non-existent record ID inside an organization you can access simply contributes no rows, rather than raising an error. Errors are reserved for authentication and authorization.

Permissions

The caller must be authenticated and a member of every organization in companyIds; the organization must be active. Beyond that, visibility is scoped per user:

• Records in workspaces the user can’t access are excluded.
• Users restricted to assigned-only records see only their own.
• Hidden lists (per role configuration) are excluded automatically.
• Tag-based access rules further narrow results.

This filtering is applied silently — restricted records are absent from items, not flagged.

Related

• Update a record
• Toggle record status
• Move a record between lists
• Manage assignees
• Manage tags
• List custom fields
• Custom field values