---
title: "bird assets list"
description: "List workspace media-library assets"
canonical: "https://bird.com/docs/cli/reference/assets-list"
---

# `bird assets list`

## Usage

```bash
bird assets list [flags]
```

## Description

Returns a cursor page, excluding deleted assets by default. Filters support kind, content type, name and folder. A folder filter excludes its subfolders; root\_only selects unfiled assets.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

## Examples

```bash
bird assets list
bird assets list | jq -r '.data[].id'
bird assets list --limit 50 --starting-after <cursor>
```

## Options

#### Filters

| Name                | Description                                                                                                                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--content-type`    | Return only assets stored with this media type. Possible values: image/png, image/jpeg, image/gif, video/mp4, video/webm, video/quicktime, audio/mpeg, audio/mp4, audio/ogg, audio/wav, application/pdf. |
| `--deleted`         | Whether to include assets that have been removed from the library. Removed assets keep serving at their original URL, so they remain listable. Possible values: exclude, include, only.                  |
| `--folder-id`       | Return only the assets filed directly in this folder. Subfolders are not included, and a folder that does not exist matches nothing. Cannot be combined with root\_only.                                 |
| `--kind`            | Return only assets in this category. This groups exact content\_type values into images, video, audio, and documents. Possible values: image, video, audio, document.                                    |
| `--q`               | A case-insensitive substring match against the asset's name.                                                                                                                                             |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                                                                         |
| `--root-only`       | Return only the assets at the top level of the library, filed in no folder. Cannot be combined with folder\_id.                                                                                          |

#### Pagination

| Name               | Description                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | Cursor from the prev\_cursor or refresh\_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev\_cursor returns the preceding page. refresh\_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. |
| `--include-total`  | When true, the response includes a total field with the total number of items matching the request's filters across all pages.                                                                                                                                                                                                                          |
| `--limit <n>`      | Maximum number of items to return per page. Allowed range: 1 to 100.                                                                                                                                                                                                                                                                                    |
| `--order`          | Sort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Possible values: asc, desc.                                                                                                                                                                                           |
| `--sort`           | Field to sort by. Defaults to created\_at. Possible values: created\_at.                                                                                                                                                                                                                                                                                |
| `--starting-after` | Cursor from the next\_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.                                                                                                                                                                                                          |

## Related

| Name                                                      | Description                               |
| --------------------------------------------------------- | ----------------------------------------- |
| [`bird assets delete`](/docs/cli/reference/assets-delete) | Remove an asset from the media library    |
| [`bird assets get`](/docs/cli/reference/assets-get)       | Get a media-library asset by ID           |
| [`bird assets update`](/docs/cli/reference/assets-update) | Update asset metadata or folder placement |
| [`bird assets upload`](/docs/cli/reference/assets-upload) | Create a media-library asset              |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)