---
title: "The lists with their properties and counts"
method: GET
path: "/api/v1/lists"
tags: ["Lists"]
---

# The lists with their properties and counts

`GET /api/v1/lists`

## Request

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

The user's lists: every live list with its id, name, icon, standing instructions, item count, layout and PROPERTIES with their stable ids — the ids create_items and update_items key values on. A list whose statusPropertyId is "status" and dueDatePropertyId is "dueDate" keeps a status and a due date on its items, which makes them tasks; the Tasks list and the Notes list are named by id. Use it to resolve a list's name to its id before writing to it, or to read a list's properties you have not seen yet. Pass suppressOptions: true when you only need names and counts; a select property can carry hundreds of options (a select value may be sent as its label). `sections` are the sidebar's sections in order (the default section, id "lists", and the ones the user made) and each list names its `section`; create_list and update_list take `section` to place a list.

## Query parameters

- `suppressOptions` boolean: true replaces each select property's option list with an optionCount — much smaller payload.

## Response `200`

The tool's result.

- object
  - `total` number, required
  - `tasksListId` string, nullable, required
  - `notesListId` string, nullable, required
  - `sections` object[], required: The sidebar's sections in the rail's order, each with its lists.
    - `id` string, required: The section's id; "lists" is the default section every account has.
    - `name` string, required
    - `isDefault` boolean, required
    - `listIds` string[], required: The section's lists in its order.
    - `isHidden` boolean: true when the user hid the section on every device.
  - `lists` object[], required
    - `id` string, required
    - `name` string, required
    - `icon` string, nullable
    - `instructions` string, nullable
    - `titleLabel` string, nullable: The title column's name on this list (Name on a CRM, Book on a reading list); null reads as Title. An item's name is its title under any label.
    - `layout` string
    - `role` 'tasks' | 'notes' | 'other': What the list's items are, read from its properties: "tasks" when it keeps the status and the due date, "notes" when it has no properties, "other" when its properties are its own.
    - `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
    - `statusPropertyId` string, nullable: "status" when the list keeps its items' status in the task columns.
    - `dueDatePropertyId` string, nullable: "dueDate" when the list keeps its items' due date in the task columns.
    - `itemCount` number: The list's open items: every live item but a repeating template, and never a completed one on a list that keeps its status in the task columns.
    - `isLifeAdmin` boolean
    - `section` object, nullable: The sidebar section the list stands in (id and name); the default section's id is "lists". null on a list somebody shared with the user that they have not filed into a section (it stands under Shared with me).
      - `id` string, required
      - `name` string, required
    - `isPinned` boolean: true when the user pinned the list to the top of the sidebar, beside Tasks.

## 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)