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

# List folders

`GET /v1/folders`

Retrieve all folders in your workspace. Folders are used to organize projects, docs, channels, dashboards, agents, and other folders into a hierarchical structure — similar to a file system.

Results can be filtered by title or parent folder, sorted by creation date or title, and are paginated.

**Tip:** To list only root-level folders, filter with `filter[parent_folder_id]=null`. To list children of a specific folder, set `filter[parent_folder_id]` to that folder's ID.

**Note:** The `folders` field (containing child folder IDs) is only populated when filtering by `parent_folder_id`. Without this filter, `folders` will be `null` for performance reasons. To retrieve child folders for a specific folder, either use `filter[parent_folder_id]` or call the **Get folder** (`GET /v1/folders/:folder_id`) endpoint.

## Query parameters

- `page` object
  - `start_cursor` string
  - `limit` integer, nullable
- `filter` object
  - `title` object — Filter results based on string value. You can either provide a `contains` operator for substring matching or an `equal_to` operator for exact matching. These options are mutually exclusive.
    - `contains` string — Substring (case-insensitive) to search for within the target string
    - `equal_to` string — Equal to operator
  - `parent_folder_id` string, nullable — Filter by parent folder ID. Pass null to get root-level folders.
- `sort` union
  - 'created_at:asc' | 'created_at:desc' | 'title:asc' | 'title:desc'
  - string[]

## Response `200`

200

- object
  - `data` object[], required
    - `id` string, required
    - `url` string — The URL of this resource in the Dovetail web app. This field is experimental and may change without notice.
    - `title` string, required
    - `type` 'folder', required
    - `created_at` string, required
    - `parent_folder` object, nullable, required
      - `id` string, required
    - `folders` object[], nullable, required
      - `id` string, required
  - `page` object, required
    - `total_count` number, required — Total number of items matching the query.
    - `has_more` boolean, required — Whether there are more items beyond the current page.
    - `next_cursor` string, nullable, required — Cursor to pass as `page[start_cursor]` to fetch the next page. Null when there are no more results.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

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