Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Bucket Objects

List Objects

This endpoint lists objects in a bucket with cursor-based pagination, filtering, and sorting.

**Filtering**: Use dot notation for metadata fields
- Example: ?metadata.type=video&metadata.status=ready

**Sorting**: Specify field and direction
- Example: ?sort_field=metadata.created_at&sort_direction=desc
- Direction: asc (ascending) or desc (descending), defaults to asc

**Pagination**: Cursor-based for efficient deep pagination
- First page: ?limit=100 (omit cursor)
- Next pages: ?limit=100&cursor={next_cursor}
- Use next_cursor from response to navigate
- No limit on pagination depth

**Total Count**: Optional (expensive operation)
- Use ?include_total=true to get total count
- Adds 50-200ms to response time
- Returns total, page, page_size, total_pages fields in pagination response
post/v1/buckets/{bucket_identifier}/objects/list

Path parameters

bucket_identifierstring required

The unique identifier of the bucket.

The unique identifier of the bucket.

Query parameters

limitinteger nullable
page_sizeinteger nullable
offsetinteger nullable
pageinteger nullable
cursorstring nullable
next_cursorstring nullable
afterstring nullable
include_totalboolean

Request body

searchstring nullable

Search term to filter objects by key or metadata

selectstring[] nullable

OPTIONAL. List of fields to include in the response. Supports dot notation for nested fields (e.g., 'metadata.title', 'status'). When specified, only the selected fields will be returned in the object results, reducing response size. System fields like 'object_id' and 'bucket_id' are always included. Use this to optimize response size when working with large objects.

return_presigned_urlsboolean nullable

Generate fresh presigned download URLs for all blobs with S3 storage. When true, each blob will include a 'presigned_url' in its properties. URLs expire after 1 hour.

Example request

{
  "filters": {
    "AND": [
      {
        "field": "name",
        "operator": "eq",
        "value": "John"
      },
      {
        "field": "age",
        "operator": "gte",
        "value": 30
      }
    ],
    "OR": [
      {
        "field": "status",
        "operator": "eq",
        "value": "active"
      },
      {
        "field": "role",
        "operator": "eq",
        "value": "admin"
      }
    ],
    "NOT": [
      {
        "field": "department",
        "operator": "eq",
        "value": "HR"
      },
      {
        "field": "location",
        "operator": "eq",
        "value": "remote"
      }
    ],
    "case_sensitive": true
  },
  "sort": {
    "field": "created_at"
  },
  "select": [
    "metadata",
    "status",
    "created_at"
  ]
}

Response

Successful Response

Example response

{
  "pagination": {
    "has_more": false,
    "limit": 10,
    "skip": 0
  },
  "results": [
    {
      "blobs": [],
      "bucket_id": "bkt_9xy8z7",
      "created_at": "2024-10-21T10:30:00Z",
      "key_prefix": "/contract-2024",
      "metadata": {
        "category": "contracts",
        "year": 2024
      },
      "object_id": "obj_123abc456def",
      "status": "DRAFT",
      "updated_at": "2024-10-21T10:30:00Z"
    }
  ]
}