S3 — bucket/search

Object Listing vs Folder Listing: Use bucket/search to search broadly across a bucket with a prefix. Use folder/get-many when you know the exact folder path and want paginated contents of that specific directory prefix.

When to Use

Prefix-filtered listing: List all files under a specific prefix (e.g. reports/2024/) to process a batch of related objects.
Existence check: Verify whether a specific object key exists in the bucket before attempting a download or copy.
Capacity reporting: Count objects in a bucket or prefix for storage usage dashboards and cost allocation reports.
Batch processing pipeline: Enumerate files landing in an S3 prefix to drive a loop that processes each file individually.
Data landing verification: Confirm that expected files have arrived in a target prefix before triggering downstream processing.

Configuration

Connection

Field	Required	Description
`accessKeyId`	Required	AWS Access Key ID. Store in BizFirst Credentials Manager.
`secretKey`	Required	AWS Secret Access Key. Never log or expose.
`sessionToken`	Optional	STS session token for temporary credentials.
`region`	Required	AWS region where the bucket resides.

Operation Fields

Field	Required	Description
`bucketName`	Required	Name of the S3 bucket to search.
`prefix`	Optional	Filter objects whose keys begin with this string (e.g. `reports/2024/`). Omit to list all objects in the bucket.
`maxKeys`	Optional	Maximum number of objects to return per page. Default: `1000`. Maximum: `1000`.
`continuationToken`	Optional	Pagination token from the previous response's `nextContinuationToken`. Omit for the first page.

Sample Configuration

{
  "connection": {
    "accessKeyId": "{{ $credentials.s3_prod.accessKeyId }}",
    "secretKey": "{{ $credentials.s3_prod.secretKey }}",
    "region": "us-east-1"
  },
  "operation": {
    "resource": "bucket",
    "action": "search",
    "bucketName": "acme-prod-documents",
    "prefix": "reports/2026/05/",
    "maxKeys": 100,
    "continuationToken": "{{ $node.PreviousPage.output.nextContinuationToken }}"
  }
}

Validation Errors

Error Code	Cause & Resolution
`NoSuchBucket`	The specified bucket does not exist or is in a different region. Verify the bucket name and the region in the connection settings.
`AccessDenied`	The IAM identity lacks `s3:ListBucket` on the target bucket. Update the IAM policy to include `s3:ListBucket` scoped to the bucket ARN.
`InvalidToken`	The `continuationToken` is invalid or expired. Tokens expire if the bucket contents change significantly between pages. Restart pagination from the first page.

Output

Success Port

Field	Type	Description
`status`	string	`success` on successful listing.
`errorCode`	string	Empty string on success.
`bucketName`	string	The bucket that was searched.
`objectCount`	int	Number of objects returned in this page (up to `maxKeys`).
`nextContinuationToken`	string	Token for retrieving the next page. Empty string if this is the last page.

Error Port

On failure, activates with errorCode, errorMessage, and httpStatusCode. Handle NoSuchBucket in deprovisioning workflows where the bucket may have already been deleted.

Sample Output

{
  "status": "success",
  "errorCode": "",
  "bucketName": "acme-prod-documents",
  "objectCount": 100,
  "nextContinuationToken": "1ycB9oIe5rD7mVBfqyZ2p4GK8sLx..."
}

Expression Reference

Expression	Result
`{{ $node.SearchBucket.output.objectCount }}`	Number of objects on this page — use in capacity reports or loop iteration counts.
`{{ $node.SearchBucket.output.nextContinuationToken }}`	Pass to the next `bucket/search` call to fetch the following page.
`{{ $node.SearchBucket.output.bucketName }}`	Confirm the searched bucket in audit log entries.

Node Policies & GuardRails

Policy Area	Recommendation
Credential Storage	Store credentials in BizFirst Credentials Manager. Never hardcode.
IAM Permissions	Grant `s3:ListBucket` scoped to the specific bucket ARN. Optionally add a condition key `s3:prefix` to restrict listing to specific prefixes.
Prefix Best Practice	Always supply a `prefix` in production workflows — listing entire large buckets is expensive and slow. Scope to the narrowest possible prefix.
Pagination Handling	Always check `nextContinuationToken`. If non-empty, the result is paginated — loop the node to fetch all pages before processing.
Token Expiry	Continuation tokens can expire if the bucket is modified between pages. Handle `InvalidToken` by restarting pagination.
High-Volume Buckets	For buckets with millions of objects, use narrow prefixes and process pages in parallel sub-workflows to avoid timeout issues.
Existence Check Pattern	To check if a specific object exists, set `prefix` to the exact key and `maxKeys: 1` — if `objectCount == 0`, the object does not exist.

Examples

Example 1: Date-Partitioned Batch Processing

A daily workflow lists all files uploaded to the current day's prefix and processes each one in a loop.

// Node: ListTodaysFiles (S3 — bucket/search)
{
  "bucketName": "acme-ingest-landing",
  "prefix": "incoming/{{ $now | date: 'YYYY/MM/DD' }}/",
  "maxKeys": 1000
}
// Node: ProcessFiles (Loop — iterate over object keys)
// Each iteration: object/download → transform → object/upload to processed/

Example 2: Pre-Download Existence Check

Before attempting a download, verify the expected report file exists in S3.

// Node: CheckReportExists (S3 — bucket/search)
{
  "bucketName": "acme-reports",
  "prefix": "monthly/2026-05/summary.pdf",
  "maxKeys": 1
}
// Node: IfExists (If Condition)
// Condition: objectCount > 0
// True: object/download → EmailAttachment
// False: GenerateReport → object/upload → EmailAttachment

Example 3: Paginated Full Bucket Inventory

A storage audit workflow iterates through all pages of a bucket to build a complete object count.

// Initial call: no continuationToken
// Loop while nextContinuationToken != ""
// Each iteration: accumulate objectCount
// Node: SearchPage (S3 — bucket/search)
{
  "bucketName": "acme-archive",
  "maxKeys": 1000,
  "continuationToken": "{{ $node.PreviousSearch.output.nextContinuationToken }}"
}
// Final: sum all objectCounts → send storage report

bucket/search FormID 20503

When to Use

Configuration

Connection

Operation Fields

Sample Configuration

Validation Errors

Output

Success Port

Error Port

Sample Output

Expression Reference

Node Policies & GuardRails

Examples

Example 1: Date-Partitioned Batch Processing

Example 2: Pre-Download Existence Check

Example 3: Paginated Full Bucket Inventory