# Amazon S3

Upload, download, copy, move and delete files in Amazon S3 or an S3-compatible store (MinIO, Wasabi, Cloudflare R2, Hetzner, IONOS), list and create buckets and folders, and make temporary download and upload links.

## Connect Amazon S3

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `amazon s3` and choose **Amazon S3**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Access Key ID · Required**: The access key’s ID (AKIA… on AWS).
- **Secret Access Key · Required**: The secret shown once when the access key was made.
- **Region · Optional**: The region code, such as eu-central-1. Empty is us-east-1. A bucket in another Amazon S3 region is found on its own; an S3-compatible store names its own (auto for Cloudflare R2, fsn1 for Hetzner).
- **Endpoint URL · Optional**: Only for an S3-compatible store: its address, such as https://s3.eu-central-1.wasabisys.com, https://\<account>.r2.cloudflarestorage.com, https://fsn1.your-objectstorage.com or https://minio.example.com:9000. Empty is Amazon S3.
- **Bucket in the Host Name · Optional**: For an S3-compatible store only. Off (the default) sends https://endpoint/bucket/key, which MinIO, Wasabi, R2, Hetzner, IONOS and Spaces accept; on sends https://bucket.endpoint/key, for a store that requires it (Alibaba Cloud OSS, Tencent COS).
- **Session Token · Optional**: Only with temporary credentials (AWS STS): the session token that goes with them. They expire within hours, so a workflow that runs for longer needs a long-term access key.

An access key pair. For Amazon S3: AWS console › IAM › Users › your user › Security credentials › Create access key, with a policy that allows what the workflows do (s3:ListAllMyBuckets, s3:ListBucket, s3:GetObject, s3:PutObject, s3:DeleteObject, s3:CreateBucket …). For an S3-compatible store, its access key and secret, and its endpoint URL.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Amazon S3**. The trigger uses the same connection as the steps.

### On File Added or Replaced

Checks a bucket or folder about once a minute and starts a run for each file added, or replaced, since the check before. The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. It reads every file in the folder (at most 5,000; pick a narrower folder for more), and a file deleted and uploaded again counts as added. The run gets the file's details; add an Amazon S3 Download step for its content.

- **Bucket · Required**: The bucket to watch.
- **Folder · Optional**: Watch only this folder, such as inbox/scans. Empty watches the whole bucket.
- **Include Subfolders · Optional**: Also watch the files in folders below it. On by default.
- **Trigger on · Required**: Which changes start a run. Options: File added, File replaced, File added or replaced. Default: File added.

A later step can use its data, such as `{{trigger.Bucket}}`, `{{trigger.ETag}}`, `{{trigger.Key}}` and 5 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Amazon S3

Add an **Amazon S3** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Bucket](https://docs.gorunner.io/apps/amazon-s3#fields-f-bucket): Create · Delete · Get Many · Search
- [File](https://docs.gorunner.io/apps/amazon-s3#fields-f-file): Upload · Download · Get Details · Get Many · Copy · Move · Delete · Get Presigned URL
- [Folder](https://docs.gorunner.io/apps/amazon-s3#fields-f-folder): Create · Delete · Get Many

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Amazon S3 can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Amazon S3 says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Amazon S3 is `pieceId: "amazons3"` with `actionId: "amazons3"`, set by `resource` and an `operation_…` field, such as `operation_bucket`. Its trigger is `amazons3trigger` / `amazons3_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Amazon S3 › Bucket

### Create

- **Name · Required**: The new bucket's name: 3–63 lowercase letters, numbers, dots and hyphens. On Amazon S3 it must be unique across every account.
- **Region · Optional**: Where to create it, such as eu-central-1. Empty is the connection's region.
- **Access (ACL) · Optional**: A canned ACL. New Amazon S3 buckets have ACLs turned off and refuse any but Private; S3-compatible stores (Spaces, Wasabi) use them for public buckets. Options: Store's default, Private, Public read, Public read and write, Any signed-in AWS account can read.
- **Object Lock · Optional**: Turn on Object Lock (and with it versioning), so files can be kept from deletion for a set time. Off by default.

### Delete

- **Bucket · Required**: The bucket to delete (it must be empty) or to search.

### Get Many

- **Name Starts With · Optional**: Only buckets whose name begins with this. Empty lists every bucket.
- **Return All · Optional**: Read every item, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–5000). Default: 100. Shows when **Return All** is off.

### Search

- **Bucket · Required**: The bucket to delete (it must be empty) or to search.
- **Key Starts With · Optional**: Only files whose key begins with this, such as invoices/2026/. Empty searches the whole bucket.
- **Group By · Optional**: A character that groups keys, usually /: keys with it after Key Starts With come back once each as a folder (a Key ending in it) instead of one by one.
- **Start After · Optional**: List only keys after this one, in alphabetical order.
- **Include Owner · Optional**: Add each file's owner. Off by default.
- **Return All · Optional**: Read every item, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–5000). Default: 100. Shows when **Return All** is off.

### Amazon S3 › File

### Upload

- **Bucket · Required**: The bucket the file is in, or goes into.
- **Folder · Optional**: The folder to put the file in, such as invoices/2026. Empty is the bucket's top level.
- **File Name · Optional**: The name to save it as, such as report.pdf. Empty uses the file's own name. A file with the same key is replaced.
- **Upload a File · Optional**: On: upload a file. Off: write the text below as the file's content. On by default.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). At most 11 MB. Shows when **Upload a File** is on.
- **Text Content · Required**: The text to save as the file (UTF-8). Set File Name too. Shows when **Upload a File** is off.
- **Content Type · Optional**: The file's MIME type, such as application/pdf. Empty uses the file's own, or one guessed from the name.
- **Access (ACL) · Optional**: A canned ACL. Buckets with ACLs turned off (the Amazon S3 default) refuse any but Private and Bucket owner full control. Options: Bucket's default, Private, Public read, Public read and write, Any signed-in AWS account can read, EC2 can read (AMI bundles), Bucket owner can read, Bucket owner full control.
- **Storage Class · Optional**: How S3 stores it: cheaper classes cost more to read back, and Glacier classes must be restored before a download. Options: Bucket's default (Standard), Standard, Intelligent-Tiering, Standard-IA, One Zone-IA, Glacier Instant Retrieval, Glacier Flexible Retrieval, Glacier Deep Archive.
- **Encryption · Optional**: Server-side encryption. Amazon S3 encrypts every new file with S3-managed keys anyway; pick KMS to use a KMS key. Options: Bucket's default, S3-managed keys (SSE-S3), AWS KMS key (SSE-KMS).
- **KMS Key ID · Optional**: The KMS key's ID or ARN. Empty uses the account's aws/s3 key. Shows when **Encryption** is **AWS KMS key (SSE-KMS)**.
- **Tags · Optional**: Object tags, such as {"project": "apollo", "retention": "1y"}. At most 10.
- **Metadata · Optional**: Custom metadata, stored as x-amz-meta-\<name>, such as {"customer-id": "C-1042"}. Plain ASCII; 2 KB in all.

### Download and Get Details

- **Bucket · Required**: The bucket the file is in, or goes into.
- **File Key · Required**: The file's full key: its folder path and name, such as invoices/2026/INV-1042.pdf.

### Get Many

- **Bucket · Required**: The bucket the file is in, or goes into.
- **Folder · Optional**: The folder to list, such as invoices/2026. Empty is the bucket's top level.
- **Include Subfolders · Optional**: Also list the files in folders below it. Off by default.
- **Return All · Optional**: Read every file, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many files to return (1–5000). Default: 100. Shows when **Return All** is off.

### Copy and Move

- **Source · Required**: The file to copy or move, as /bucket/key, such as /acme-documents/inbox/scan.pdf.
- **Destination · Required**: Where it goes, as /bucket/key, such as /acme-archive/2026/scan.pdf. A file there is replaced. At most 5 GB per file.

### Delete

- **Bucket · Required**: The bucket the file is in, or goes into.
- **File Key · Required**: The file's full key: its folder path and name, such as invoices/2026/INV-1042.pdf.
- **Version ID · Optional**: Delete this version for good (a bucket that keeps versions). Empty deletes the current file, which in such a bucket leaves a delete marker.

### Get Presigned URL

- **Bucket · Required**: The bucket the file is in, or goes into.
- **File Key · Required**: The file's full key: its folder path and name, such as invoices/2026/INV-1042.pdf.
- **Link For · Optional**: Download (GET) the file, or upload (PUT) one to this key without a credential. Options: Download, Upload. Default: Download.
- **Expires In (minutes) · Optional**: How long the link works: 1 minute to 7 days (10,080). With temporary credentials it stops when they expire. Default: 60.

### Amazon S3 › Folder

### Create

- **Bucket · Required**: The bucket the folder is in.
- **Parent Folder · Optional**: The folder to make it in, such as invoices. Empty is the bucket's top level.
- **Folder Name · Required**: The new folder's name, such as 2026.

### Delete

- **Bucket · Required**: The bucket the folder is in.
- **Folder · Optional**: The folder's key, such as invoices/2026. For Get Many, empty lists the top-level folders.

### Get Many

- **Bucket · Required**: The bucket the folder is in.
- **Folder · Optional**: The folder's key, such as invoices/2026. For Get Many, empty lists the top-level folders.
- **Return All · Optional**: Read every folder, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many folders to return (1–5000). Default: 100. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/amazon-s3