---
title: ListObjectsV2 · S3 API
description: Lists the objects in a bucket, one page at a time.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# ListObjectsV2

`GET /{bucket}?list-type=2`

Lists the objects in a bucket, one page at a time.

Returns the current version of each object, in key order. Use `prefix` and `delimiter` to browse keys like folders.

- Role: Viewer or higher.
- Support: supported.
- Auth: AWS Signature Version 4 with your API key. See [S3 API](/api/s3.md).
- prefix, delimiter, continuation-token, start-after, max-keys, and encoding-type.
- `max-keys` counts keys before storage groups them by the delimiter. So a page can hold fewer entries, and one common prefix can appear on more than one page.
- Storage ignores `fetch-owner`. Contents has no Owner.

## Example request

```http
GET /support-tickets?list-type=2&prefix=incidents%2F&delimiter=%2F HTTP/1.1
Host: wspq7ws2np5l8z4.storage.beta.graphon.sh
x-amz-date: 20261007T093000Z
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: AWS4-HMAC-SHA256 Credential=<ACCESS_KEY_ID>/20261007/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=<SIGNATURE>
```

## Path parameters

- `bucket` (string, required): The bucket name.

## Query parameters

- `list-type` (string, required): Send `2`. It selects this operation.
- `prefix` (string, optional): Return only keys that start with this value.
- `delimiter` (string, optional): Group the keys that contain this value after the prefix into CommonPrefixes. Usually `/`.
- `max-keys` (integer, optional): The most keys to return. Storage clamps the value to 1 through 1,000. Default: `1000`.
- `continuation-token` (string, optional): The NextContinuationToken of the previous page. Send it to get the next page.
- `start-after` (string, optional): Return only keys after this key.
- `encoding-type` (string, optional): Send `url` to percent-encode the keys, prefixes, and delimiter in the response. Values: `url`.

## Headers

- `x-amz-expected-bucket-owner` (string, optional): The workspace ID that must own the bucket. Another owner returns `403 AccessDenied`.

## Responses

### 200 · OK

One page of objects.

Response body:

- `ListBucketResult` (object, required): The root element.
  - `Name` (string, optional): The bucket name.
  - `Prefix` (string, optional): The prefix of the request.
  - `Delimiter` (string, optional): The delimiter of the request.
  - `EncodingType` (string, optional): Present when the request sent `encoding-type`.
  - `KeyCount` (integer, optional): The number of Contents and CommonPrefixes elements.
  - `MaxKeys` (integer, optional): The page size that storage used.
  - `IsTruncated` (boolean, optional): `true` when more keys follow.
  - `NextContinuationToken` (string, optional): Present when IsTruncated is `true`. Send it as `continuation-token`.
  - `Contents` (array, optional): One element for each object.
    - `Key` (string, optional): The object key.
    - `LastModified` (string, optional): When the object was written, as an ISO 8601 time.
    - `ETag` (string, optional): The entity tag, in double quotes.
    - `Size` (integer, optional): The size in bytes.
    - `StorageClass` (string, optional): The storage class that the write recorded.
  - `CommonPrefixes` (array, optional): One element for each group of keys.
    - `Prefix` (string, optional): The prefix that the keys share, up to the delimiter.

```http
HTTP/1.1 200 OK
Content-Type: application/xml
x-amz-request-id: 4F8A2C7D1E6B4093A5C2D8E1F7B3A960

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>support-tickets</Name>
  <Prefix>incidents/</Prefix>
  <Delimiter>/</Delimiter>
  <KeyCount>2</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>incidents/checkout-timeout.json</Key>
    <LastModified>2026-10-07T09:30:00.000Z</LastModified>
    <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
    <Size>34</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>incidents/2026/</Prefix>
  </CommonPrefixes>
</ListBucketResult>
```

## Errors

Any request can also get the common errors on [S3 API](/api/s3.md).

### 404 · `NoSuchBucket`

No bucket has this name, or the bucket was deleted.

Check the bucket name. ListBuckets shows the buckets of the workspace.

### 403 · `AccessDenied`

The key does not have the role for this operation, or the bucket is in another workspace.

Use a key of the workspace that owns the bucket, with the role above.

## Other request languages

### aws CLI

```bash
# The graphon profile from the S3 API overview.
export AWS_PROFILE=graphon

aws s3 ls s3://support-tickets/incidents/
```

### Python (boto3)

```python
# Replace wspq7ws2np5l8z4 with your workspace ID.
import os

import boto3
from botocore.config import Config

api_key = os.environ["GRAPHON_API_KEY"]
access_key_id = api_key.split("_", 1)[1].split(".")[0]

s3 = boto3.client(
    "s3",
    endpoint_url="https://wspq7ws2np5l8z4.storage.beta.graphon.sh",
    region_name="us-east-1",
    aws_access_key_id=access_key_id,
    aws_secret_access_key=api_key,
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

response = s3.list_objects_v2(
    Bucket="support-tickets",
    Prefix="incidents/",
    Delimiter="/",
)
for item in response.get("Contents", []):
    print(item["Key"], item["Size"])
```

### JavaScript (AWS SDK)

```javascript
// Replace wspq7ws2np5l8z4 with your workspace ID.
import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';

const apiKey = process.env.GRAPHON_API_KEY;
if (!apiKey) throw new Error('Set GRAPHON_API_KEY.');
const accessKeyId = apiKey.split('_')[1].split('.')[0];

const s3 = new S3Client({
  endpoint: 'https://wspq7ws2np5l8z4.storage.beta.graphon.sh',
  region: 'us-east-1',
  forcePathStyle: true,
  credentials: { accessKeyId, secretAccessKey: apiKey },
});

const response = await s3.send(new ListObjectsV2Command({
  Bucket: 'support-tickets',
  Prefix: 'incidents/',
  Delimiter: '/',
}));
console.log(response.Contents?.map((item) => item.Key));
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.