# tigris objects list

List objects in a bucket, optionally filtered by a key prefix.

**Alias:** `l`

## Usage[​](#usage "Direct link to Usage")

```
tigris objects list <bucket> [flags]

t3 o l <bucket> [flags]
```

## Flags[​](#flags "Direct link to Flags")

| Name                              | Required | Default | Description                                                                                                                                                                        |
| --------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--prefix`, `-p`                  | No       | —       | Filter objects by key prefix (e.g. "images/" to list only images)                                                                                                                  |
| `--format`, `-f`                  | No       | `table` | Output format. Options: `json`, `table`, `xml`                                                                                                                                     |
| `--limit`                         | No       | —       | Maximum number of items to return per page                                                                                                                                         |
| `--page-token`, `-pt`             | No       | —       | Pagination token from a previous request to fetch the next page                                                                                                                    |
| `--deleted`                       | No       | —       | List [soft-deleted](/docs/buckets/soft-delete/.md) objects instead of live ones                                                                                                    |
| `--snapshot-version`, `-snapshot` | No       | —       | Read from a specific bucket snapshot. Accepts a snapshot version string or any UNIX nanosecond-precision timestamp (e.g. `1765889000501544464`)                                    |
| `--source`                        | No       | —       | List objects from a specific storage source on buckets with shadow migration enabled. Options: `tigris` (objects already in Tigris), `shadow` (objects still on the shadow source) |

## Examples[​](#examples "Direct link to Examples")

```
tigris objects list my-bucket

tigris objects list my-bucket --prefix images/

tigris objects list my-bucket --format json



# As of a snapshot

tigris objects list my-bucket --snapshot-version 1765889000501544464



# On a shadow-migrated bucket, only objects still on the source

tigris objects list my-bucket --source shadow
```

## Listing soft-deleted objects[​](#listing-soft-deleted-objects "Direct link to Listing soft-deleted objects")

On a bucket with [soft delete](/docs/buckets/soft-delete/.md) enabled, `--deleted` switches the listing over to the objects that have been deleted but are still inside their retention window:

```
tigris objects list my-bucket --deleted

tigris objects list my-bucket --prefix contracts/ --deleted
```

This is a separate view rather than an addition — the output contains only deleted objects, and live ones are left out. `--prefix`, `--limit`, and `--page-token` work the same way here.

To act on one of these entries you need a version ID, which [`objects list-versions --deleted`](/docs/cli/objects/list-versions/.md) provides. From there, [`objects restore-deleted`](/docs/cli/objects/restore-deleted/.md) brings a version back and [`objects purge`](/docs/cli/objects/purge/.md) destroys one permanently.