---
url: /process-functions/s3bucket.md
description: Lists, uploads, downloads and shares objects in an Amazon S3 bucket.
---

#  S3Bucket

Lists, uploads, downloads and shares objects in an Amazon S3 bucket.

```js
const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

bucket.downloadFile("imports/budget.csv", "uploads/budget.csv");
```

## Constructor

### datasource.S3Bucket `datasource.S3Bucket(accessKey, secretKey, bucket, region)`  {#datasource-s3bucket}

Connects to an S3 bucket and returns an `S3Bucket`. The connection is checked straight away, so it throws if the credentials are wrong or the bucket doesn't exist.

| Parameter | Type | Description |
|---|---|---|
| `accessKey` | `string` | The AWS access key id. |
| `secretKey` | `string` | The AWS secret access key. |
| `bucket` | `string` | The name of the bucket. |
| `region` | `string` | The bucket's AWS region, for example `"ap-southeast-2"`. |

```js
const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);
```

::: tip Keep keys out of your scripts
Store the access key and secret key as [Secrets](/process-functions/security-getsecret) and read them with `security.getSecret`, rather than writing them into the script.
:::

## Overview

* **Objects and keys:** each file in a bucket is an object, identified by its key, such as `"exports/2026/actuals.csv"`. Keys can look like folder paths.
* **Listing:** [list()](#list) returns every object in the bucket. For large buckets, or to look inside one "folder", use [listPaginiated()](#listpaginiated).
* **Sharing:** [generatePresignedURL()](#generatepresignedurl) creates a link that anyone can use to download an object until it expires, without AWS credentials.

## Methods

### list `list()`  {#list}

Returns every object in the bucket. Each object has:

* `name`: the object's key.
* `size`: its size in bytes.
* `last_modified`: when it was last changed, as an ISO timestamp string.

### uploadFile `uploadFile(objectKey, uploadedFilename)` {#uploadfile}

Uploads a file to the bucket. Throws if the credentials don't allow writing to the bucket.

| Parameter | Type | Description |
|---|---|---|
| `objectKey` | `string` | The key to store the object under. |
| `uploadedFilename` | `string` | The path of the file to upload. |

### downloadFile `downloadFile(objectKey, outputFile)` {#downloadfile}

Downloads an object from the bucket to a file. Throws if the object doesn't exist or the credentials don't allow reading it.

| Parameter | Type | Description |
|---|---|---|
| `objectKey` | `string` | The key of the object to download. |
| `outputFile` | `string` | The path to save it to. |

### generatePresignedURL `generatePresignedURL(objectKey, expiresAfterMinutes)`  {#generatepresignedurl}

Returns a link that downloads an object without AWS credentials until it expires.

| Parameter | Type | Description |
|---|---|---|
| `objectKey` | `string` | The key of the object. |
| `expiresAfterMinutes` | `number` | How many minutes the link works for. The minimum is `1`. |

### close `close()`  {#close}

Closes the connection to the bucket. The bucket closes automatically when the process finishes, so only call this to close it early.

## Examples

### Download every file in a folder

```js
const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

const page = bucket.listPaginiated("imports/2026/", 100, 1);

for (const object of page.results) {
    const fileName = object.name.split("/").pop();
    bucket.downloadFile(object.name, "uploads/" + fileName);
}
```

### Upload an export

```js
const bucket = datasource.S3Bucket(
    security.getSecret("S3_ACCESS_KEY"),
    security.getSecret("S3_SECRET_KEY"),
    "my-company-data",
    "ap-southeast-2"
);

bucket.uploadFile("exports/2026/actuals.csv", "exports/actuals.csv");
```

## Related

* [security.getSecret](/process-functions/security-getsecret): reads a stored secret, such as an access key.