---
title: "Filter, sort, count or sum the items of one list"
method: POST
path: "/api/v1/items/query"
tags: ["Items"]
---

# Filter, sort, count or sum the items of one list

`POST /api/v1/items/query`

## Request

- Base URL: `https://api.roma.app`
- URL: `https://api.roma.app/api/v1/items/query`
- Auth: HTTP bearer

Filter, sort, count or sum the items of ONE list by its properties — exact numbers instead of eyeballing a dump: "how many are unread", "expenses in March", "the wines rated 5". `where` clauses AND-combine on a property by id or name (on a list that keeps them, `status` and `dueDate` are properties too); a select value may be its label. mode 'list' (default) returns the matching items, paged with offset and limit; 'count' how many match; 'sum' the total of `sumPropertyId` across the matches. Archived items are left out unless includeArchived: true; each item reports its archivedAt.

## Request body

- object
  - `listId` string, required: The list to query: a list id (from list_lists or get_context), or the word "tasks" (the Tasks list, the unsorted pool) or "notes" (the Notes list, made afresh when the user deleted theirs).
  - `where` object[], nullable: Filter clauses, AND-combined. Omit for every item.
    - `propertyId` string, required: The property to filter on — its stable id or its name. 'title' on every list; 'status' and 'dueDate' on a list that keeps them.
    - `op` 'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'in' | 'notIn' | 'isNull' | 'notNull' | 'within', required: Comparison operator. 'in'/'notIn' expect `value` to be an array; 'isNull'/'notNull' ignore `value`. Text comparisons are case-insensitive.
    - `value` union: The value to compare against (a string/number/boolean, or an array for 'in'/'notIn'). Omit for 'isNull'/'notNull'.
      - string
      - number
      - boolean
      - string[]
  - `sort` object, nullable: Sort order. Omit for the list's default (newest first).
    - `propertyId` string, required: The property to sort by — its stable id or name.
    - `dir` 'asc' | 'desc', required: Sort direction.
  - `mode` 'list' | 'count' | 'sum', nullable: 'list' (default) returns matching items; 'count' how many match; 'sum' totals `sumPropertyId` across matches.
  - `sumPropertyId` string, nullable: For mode 'sum': the numeric property to total (its stable id or name).
  - `createdAfter` string, nullable: ISO 8601 instant — items added on/after this.
  - `createdBefore` string, nullable: ISO 8601 instant — items added before this (exclusive).
  - `updatedAfter` string, nullable: ISO 8601 instant — items last edited on/after this. A read that repeats on a schedule passes the instant of its previous read here, or uses list_items' `changedSince`, which also carries deletions.
  - `updatedBefore` string, nullable: ISO 8601 instant — items last edited before this (exclusive).
  - `includeArchived` boolean, nullable: true also includes archived items (hidden from every list by default), so one can be brought back with update_items.
  - `limit` integer, nullable: mode 'list': max items per page (default 50).
  - `offset` integer, nullable: mode 'list': items to skip — page through a big list with offset + limit until hasMore is false.
  - `includeImageUrls` boolean, nullable: mode 'list': true additionally returns a short-lived signed `url` per attachment.

## Response `200`

The tool's result.

- object
  - `mode` 'list' | 'count' | 'sum', required
  - `listId` string, required
  - `listName` string, required
  - `listIcon` string, nullable: The list's own icon, an emoji, when it has one.
  - `count` number, required: How many items match.
  - `sum` number
  - `sumPropertyId` string
  - `properties` object[]
    - `id` string, required
    - `name` string, required
    - `type` string, required
    - `kind` string: What the property IS: "status" / "dueDate" for the reserved pair a list binds to the task columns, else its type. A select named Status on any other list is a plain select.
    - `options` object[]
      - `id` string, required
      - `label` string, required
    - `optionCount` number
  - `items` object[]
    - `id` string, required
    - `identifier` string, nullable: The item's fixed ID — its list's prefix and a number, TASK-1601 — which every item tool takes as its id too.
    - `title` string, nullable
    - `body` string, nullable: The body as Markdown; with a short handle in front of every block on a read made for editing.
    - `bodyVersion` string: A fingerprint of the body as read; a whole-body `rewrite` names it as `baseVersion`.
    - `taskStatus` string, nullable: On a list that keeps a status.
    - `dueAt` string, nullable: On a list that keeps a due date: the instant stored; a day when hasDueTime is false.
    - `hasDueTime` boolean, nullable: Whether dueAt's time of day is meant; false for a day.
    - `reminderAt` string, nullable: When the reminder rings, as an instant; null for none.
    - `completedAt` string, nullable
    - `values` object: The item's values keyed by property id; a select value is an option id.
    - `cells` object: The item's values by property NAME, as text, where its list has properties of its own.
    - `isSharedWithMe` boolean: Shared with the person by its owner; `editable` says what update_items admits on it.
    - `editable` 'all' | 'titleAndBody': On a row shared with the person: `titleAndBody` for an item shared with them one by one (its status, due date, values and images are its owner's; update_items refuses them by name), `all` for an item on a list shared with them (every field but the owner's favorite).
    - `listId` string, nullable
    - `listName` string, nullable
    - `listIcon` string, nullable: The list's own icon, an emoji, when it has one.
    - `expertId` string, nullable: The id of the item's standing expert (one of the user's experts, list_experts), when the user's own item carries one: that expert answers by default in the item's chat in Roma. Absent on a row shared with the user.
    - `createdAt` string, nullable
    - `updatedAt` string, nullable
    - `editedAt` string, nullable
    - `archivedAt` string, nullable
    - `recordingStatus` string
    - `attachments` object[]
      - `bucketPath` string, required
      - `mimeType` string, required
      - `sizeBytes` number, required
      - `url` string
    - `bodyImages` object[]: The pictures the body shows (`![…](roma://attachment/<bucketPath>)`), whether or not they are attachments, with the size each was stored at (null when unknown) and its alt text; with includeImageUrls, a short-lived signed url on each; with includeImages on get_item, the pictures themselves as image content blocks.
      - `bucketPath` string, required
      - `width` number, nullable, required
      - `height` number, nullable, required
      - `alt` string, required
      - `url` string
  - `offset` number
  - `hasMore` boolean

## Other responses

- `400`: The request was understood and refused; the error says what to change.
- `401`: No usable bearer token.
- `404`: No such item for this account.
- `405`: The path exists but not with this method; Allow lists the ones that work.
- `429`: Over the rate limit; wait for Retry-After.

---

[API](https://skmtc.dev/roma/apis/roma-api.md) - [All operations](https://skmtc.dev/roma/apis/roma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roma/apis/roma-api/revisions/3dd91459b0fb?raw)