List objects in a bucket

Returns the bucket's active (non-deleted) objects, newest first, using keyset pagination.

Endpoint

GET https://api.dairo.app/v1/buckets/{bucketId}/objects

Returns the bucket's active (non-deleted) objects, newest first, using keyset pagination. limit defaults to 20 and is clamped to the range 1–100. When more objects remain, the response includes an opaque nextCursor; pass it back as the cursor query parameter to fetch the following page. Each object carries its bytes, filename, contentType, and current scanStatus (pending, clean, infected, failed, or skipped). Requires buckets:read.

Scope: buckets:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl "https://api.dairo.app/v1/buckets/3fa85f64-5717-4562-b3fc-2c963f66afa6/objects" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Path parameters

Name	Type	Required	Description
`bucketId`	string	yes	Bucket identifier (buk_*).

Query parameters

Name	Type	Required	Description
`limit`	integer	no	Maximum number of items in the page. (minimum 1, maximum 100, default `25`)
`cursor`	string	no	The `nextCursor` of the previous page; omit it for the first page (Pagination).

Response

200 Success. Body: application/json, BucketObjectListResponse.

Field	Type	Required
`object`	`"list"`	yes
`data`	array of BucketObject	yes
`pagination`	Pagination	yes

200

{
  "object": "list",
  "data": [
    {
      "object": "bucket_object",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "filename": "string",
      "contentType": null,
      "bytes": 0,
      "scanStatus": "pending",
      "createdAt": "2026-10-19T09:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`409`	The resource already exists or its state does not allow this (`duplicate_resource` or a condition-specific code).
`422`	The request is well-formed but a field failed validation (`validation_failed`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).