---
title: "List files"
method: GET
path: "/api/buckets/{namespace}/{repo}/tree/{path}"
tags: ["buckets"]
---

# List files

`GET /api/buckets/{namespace}/{repo}/tree/{path}`

## Path parameters

- `namespace` string, required
- `repo` string, required
- `path` string, required — Wildcard path parameter

## Query parameters

- `limit` integer
- `cursor` string — Pagination cursor
- `recursive` string — When false, returns collapsed directory entries instead of listing all files recursively. The number of entries returned can then be less than the limit, but there will always be a pagination link if there are more entries. Note: non-recursive listing hasn't a strong consistency guarantees.
- `sort` 'path' | 'uploadedAt' — Sort order. `path` (default) sorts lexicographically; `uploadedAt` sorts by most recent upload first. In recursive mode `uploadedAt` is only supported at the bucket root (no path prefix). In non-recursive mode, only supported at root or exact folder prefixes.
- `direction` 'asc' | 'desc' — Sort direction. Defaults to `asc` for `path` and `desc` for `uploadedAt`.

## Response `200`

List of files and directories

- object[]
  - `type` 'file' | 'directory', required
  - `path` string, required
  - `size` integer
  - `xetHash` string — Not defined for directories
  - `mtime` string, date-time
  - `mtimeNanos` integer — Sub-millisecond remainder of mtime, in nanoseconds (0–999_999)
  - `uploadedAt` string, date-time, required
  - `contentType` string

## Changes

- **2026-09-08** `bd17546f47b8` — 2 breaking, 5 info
  - for the `query` request parameter `recursive`, default value `true` was removed
  - the `items/type` response's property type changed from no type to `string` for status `200`
  - for the `query` request parameter `direction`, the type was generalized from no type to `string`
  - for the `query` request parameter `recursive`, the type was generalized from no type to `string`
  - …3 more

[Change history](https://skmtc.dev/huggingface/apis/hub-api-endpoints/changes/api/buckets/:namespace/:repo/tree/:path/get.md)

---

[API](https://skmtc.dev/huggingface/apis/hub-api-endpoints.md) · [All operations](https://skmtc.dev/huggingface/apis/hub-api-endpoints/llms.txt) · [OpenAPI document](https://skmtc.dev/huggingface/apis/hub-api-endpoints/revisions/2be5f0669ac6?raw)