Sign in
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"
    }
  ]
}

Changes

Changed in 5 of the 33 revisions of this API.212

  • 1c7f318214241See the full diff
    • ●

      added the new signals enum value to the //// response property for the response status

      response-property-enum-value-added

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 9603dfdab4631See the full diff
    • ●

      added the new DEACTIVATED enum value to the // response property for the response status

      response-property-enum-value-added

  • 72cc17ba6f7f2See the full diff
    • ○

      added the new optional query request parameter after

      new-optional-request-parameter

    • ○

      added the new optional query request parameter next_cursor

      new-optional-request-parameter

  • 7cb0515333119See the full diff
    • ○

      added the new geo_bounding_box enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_bounding_box enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_polygon enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new geo_radius enum value to the request property //////

      request-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog