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.

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 position, 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, todoListPosition_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-workspace scans, the optional after argument provides a keyset cursor that seeks directly to the page boundary through an index, so page 100 costs the same as page 1.

after 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:

• The query is scoped to a single workspace that does not use multi-list records (records that appear in more than one list). Cross-workspace queries are not supported yet — use skip.
• sort is exactly [position_DESC]. Passing any other sort — including omitting sort — is rejected; use skip for other orderings.
• after is not combined with skip.

To start a chain, run a request that meets those conditions (with or without skip) and read pageInfo.nextCursor — an eligible offset request hands back a usable cursor from page 1, so there is no dedicated “give me a cursor” round trip. Pass that value as after on the next request, and keep following nextCursor until it returns null, which marks the final page.

Cursor pages skip the exact-count query for speed, so pageInfo.totalItems and totalPages come back null on any request that passes after. Drive the loop with hasNextPage/nextCursor instead of a total.

query CursorPage {
  recordQueries {
    todos(
      filter: { companyIds: ["company_123"], projectIds: ["project_123"] }
      sort: [position_DESC]
      limit: 100
      after: "eyJwb3NpdGlvbiI6..."
    ) {
      items {
        id
        title
      }
      pageInfo {
        hasNextPage
        nextCursor
      }
    }
  }
}

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