---
title: "List Folders"
method: GET
path: "/agents/folders"
tags: ["Folders"]
---

# List Folders

`GET /agents/folders`

List [knowledge base](/line/knowledge-base) folders

## Query parameters

- `parent_ids[]` string[]
- `depth` integer
- `starting_after` string
- `ending_before` string
- `limit` integer

## Headers

- `Cartesia-Version` '2026-03-01', date, required

## Response `200`

A paginated tree of folders.

- ListFoldersResponse
  - `data` FolderTreeResponse[], required — The paginated list of top-level folders matching the request.
    - `id` string, required — The ID of the folder.
    - `parent_id` string, nullable, required — The ID of the parent folder, or `null` for top-level folders.
    - `name` string, required — The folder's name.
    - `created_at` string, date-time, required — When the folder was created.
    - `agents` FolderAgentSummary[], required — Agents that have access to this folder.
      - `id` string, required — The ID of the agent.
      - `name` string, required — The name of the agent.
    - `documents` FolderDocumentSummary[], required — Documents inside this folder.
      - `id` string, required — The ID of the document.
      - `name` string, nullable, required — The document's display name, or `null` if unnamed.
      - `created_at` string, date-time, required — When the document was uploaded.
      - `metadata` object, required — User-defined string-keyed metadata.
    - `children` FolderResponse[], required — Nested subfolders, up to the requested `depth`. Each child has the same shape as this object, including its own `children`.
      - `id` string, required — The ID of the folder.
      - `parent_id` string, nullable, required — The ID of the parent folder, or `null` for top-level folders.
      - `name` string, required — The folder's name.
      - `created_at` string, date-time, required — When the folder was created.
      - `agents` FolderAgentSummary[], required — Agents that have access to this folder.
        - `id` string, required — The ID of the agent.
        - `name` string, required — The name of the agent.
      - `documents` FolderDocumentSummary[], required — Documents inside this folder.
        - `id` string, required — The ID of the document.
        - `name` string, nullable, required — The document's display name, or `null` if unnamed.
        - `created_at` string, date-time, required — When the document was uploaded.
        - `metadata` object, required — User-defined string-keyed metadata.
  - `has_more` boolean, required — Whether more results are available after this page.
  - `next_page` string, nullable — An ID that can be passed as `starting_after` or `ending_before` to get the next page.

---

[API](https://skmtc.net/cartesia/apis/cartesia-api.md) · [All operations](https://skmtc.net/cartesia/apis/cartesia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cartesia/cartesia-api/revisions/8910812440d3/schema)