Pagination & Filtering

Almost every list query in the Blue API is paginated, and most accept a filter. This page documents the conventions so you don’t have to relearn them per query: the two pagination styles, the PageInfo shape returned by both, the default and maximum page sizes, and the shared filter input used to narrow record queries. Records are Todo objects and workspaces are Project objects in the API.

Two pagination styles

Blue has two pagination idioms. The offset style is dominant — roughly 35 queries use it — and is the one to reach for. A handful of older *List queries expose cursor-style arguments (first/last/after/before), but their resolvers only honor a subset of those args. When in doubt, use the offset style.

Offset style (recommended)

Offset queries take a skip (how many rows to skip) and a page-size argument — either take or limit depending on the query — and return a container object with items and a pageInfo:

query ListForms {
  forms(skip: 0, take: 20) {
    items {
      id
      title
    }
    pageInfo {
      totalItems
      totalPages
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

{
  "data": {
    "forms": {
      "items": [
        { "id": "clm4n8qwx000008l0g4oxdqn7", "title": "Bug intake" },
        { "id": "clm4n8qwx000108l0h7pterz2", "title": "Customer feedback" }
      ],
      "pageInfo": {
        "totalItems": 42,
        "totalPages": 3,
        "page": 1,
        "perPage": 20,
        "hasNextPage": true,
        "hasPreviousPage": false
      }
    }
  }
}

The page-size argument is named take on most queries (forms, customFields, projectList, templates, …) and limit on the record-oriented queries (todoQueries { todos }, publicViewRecords). The skip argument is always skip. A couple of container types also carry a totalCount field, but it’s deprecated in favor of pageInfo.totalItems — don’t select it.

Cursor style (partial — legacy)

Three *List queries — companyUserList, commentList, and activityList — expose the relay-flavored after, before, first, last, and orderBy arguments alongside skip. Their resolvers do not implement full bidirectional cursoring. What each actually honors:

Because before/last are no-ops on these queries, treat them as offset queries: page forward with skip (or with the keyset after cursor on commentList/activityList), and read pageInfo to know when to stop. The deprecated pageInfo.startCursor/pageInfo.endCursor fields are not populated by these resolvers.

PageInfo

Both styles return a PageInfo object. Select these fields:

Default and maximum page sizes

skip defaults to 0 everywhere. The page-size default varies by query:

publicViewRecords is stricter than the others: it accepts a limit of only 25 or 150, requires skip to be a non-negative multiple of limit, and rejects skip above 10000. Out-of-range values return BAD_USER_INPUT.

Driving a pagination loop

Page off skip plus pageInfo.hasNextPage. Start at skip: 0, then add the page size each round until hasNextPage is false:

query RecordsPage($skip: Int!) {
  todoQueries {
    todos(filter: { companyIds: ["company_123"] }, limit: 100, skip: $skip) {
      items {
        id
        title
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Send the query with { "skip": 0 }, read hasNextPage, and re-send with { "skip": 100 }, { "skip": 200 }, and so on while hasNextPage is true. totalItems lets you size the loop up front (ceil(totalItems / perPage) requests).

Counting without fetching

If you only need the size of a result set, use the count-only companion query rather than paging through items. The records query has todosCount, which takes the same filter input and returns a bare Int!:

query CountRecords {
  todosCount(filter: { projectIds: ["project_123"], showCompleted: false })
}

{ "data": { "todosCount": 128 } }

todosCount also accepts an optional refetchedAt: DateTime argument to bypass cached counts.

Filtering records

The record queries share a filter vocabulary. todoQueries { todos } and publicViewRecords take a TodosFilter! (its companyIds is required); todosCount and activityList take a TodoFilterInput. The two inputs overlap heavily — the table below covers the most useful TodoFilterInput fields. (TodosFilter adds the required companyIds plus todoIds, todoListTitles, search ranges, and more.)

TodoFilterInput

The input also exposes negation arrays (notAssigneeIds, notTagIds, notColors, notTodoListIds), existence booleans (hasTag, hasDueDate, hasChecklist, hasDependency, hasReference, …), completed-date range (completedStart/completedEnd), and last-updated-by axes (lastUpdatedByUserIds, lastUpdatedByAutomationIds, lastUpdatedByActorTypes). Grep the schema for the full set.

Filter operators

Two enums drive how conditions combine and compare.

FilterLogicalOperator joins conditions or groups:

FilterComparisonOperator is the per-condition comparison (used within fields entries):

Filtering example

Active records in two workspaces, assigned to a given user, whose title contains “launch”:

query FilteredRecords {
  todoQueries {
    todos(
      filter: {
        companyIds: ["company_123"]
        projectIds: ["project_123", "project_456"]
        assigneeIds: ["user_123"]
        showCompleted: false
        q: "launch"
      }
      sort: [duedAt_ASC]
      limit: 50
    ) {
      items {
        id
        title
        done
        duedAt
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Errors

Related

• List records
• List workspaces
• List custom fields
• List users
• Making requests
• Error codes