Skip to main content

List Objects

List files in your WAYSCloud Storage buckets with filtering and pagination.

Endpoint​

GET /v1/storage/{bucket}/

Query Parameters​

  • prefix - Filter by key prefix
  • delimiter - Group by delimiter (typically /)
  • marker - Pagination marker
  • max-keys - Max results (default: 1000)

List All Objects​

cURL​

curl -X GET "https://api.wayscloud.services/v1/storage/my-bucket/" \
  -H "Authorization: Bearer wayscloud_storage_abc123_YourSecretKey"

Python​

import requests
import os
import xml.etree.ElementTree as ET

API_KEY = os.getenv('WAYSCLOUD_API_KEY')

response = requests.get(
    'https://api.wayscloud.services/v1/storage/my-bucket/',
    headers={'Authorization': f'Bearer {API_KEY}'}
)

# Parse XML response
root = ET.fromstring(response.content)
for obj in root.findall('.//{http://s3.amazonaws.com/doc/2006-03-01/}Contents'):
    key = obj.find('{http://s3.amazonaws.com/doc/2006-03-01/}Key').text
    size = obj.find('{http://s3.amazonaws.com/doc/2006-03-01/}Size').text
    print(f'{key} ({size} bytes)')

List with Prefix​

# List all files in "documents/" folder
curl -X GET "https://api.wayscloud.services/v1/storage/my-bucket/?prefix=documents/" \
  -H "Authorization: Bearer $WAYSCLOUD_API_KEY"

List with Delimiter​

# List folders in root
curl -X GET "https://api.wayscloud.services/v1/storage/my-bucket/?delimiter=/" \
  -H "Authorization: Bearer $WAYSCLOUD_API_KEY"

Response Format​

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
    <Name>my-bucket</Name>
    <Prefix></Prefix>
    <Marker></Marker>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>document.pdf</Key>
        <LastModified>2025-11-04T10:30:00.000Z</LastModified>
        <ETag>"a1b2c3d4e5f6789"</ETag>
        <Size>1048576</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>

Pagination​

def list_all_objects(bucket):
    marker = None
    all_objects = []
    
    while True:
        params = {'max-keys': 1000}
        if marker:
            params['marker'] = marker
        
        response = requests.get(
            f'https://api.wayscloud.services/v1/storage/{bucket}/',
            headers={'Authorization': f'Bearer {API_KEY}'},
            params=params
        )
        
        # Parse and collect objects
        # ... parse XML ...
        
        # Check if more results
        if not is_truncated:
            break
        
        marker = last_key
    
    return all_objects

Next Steps​