Bucket Storage

Utils

Device+job scoped persistent storage that survives across task iterations

Access bucket storage through agent.utils.bucket. Bucket data is scoped to a specific device + job combination and persists across task iterations. Use it to store session tokens, login state, or any data that should survive between tasks on the same device.

Note

Bucket is only available when the automation is running through a job. Calling these methods outside of a job context will return an error.

BucketUtils Interface

TypeScript

interface BucketUtils {
  get(): Promise<
    { success: false; error: string } |
    { success: true; bucket: Bucket }
  >;

  set(data: Partial<Bucket>): Promise<
    { success: false; error: string } |
    { success: true; bucket: Bucket }
  >;
}

get()

TypeScript

get(): Promise<{ success: false; error: string } | { success: true; bucket: Bucket }>

Retrieves the current bucket data for this device+job combination. Returns the stored data object, or an empty object if no bucket exists yet.

Returns

{ success: true; bucket: Bucket } | { success: false; error: string }The stored bucket data on success, or an error message

Examples

Read bucket data

TypeScript

const result = await agent.utils.bucket.get();

if (result.success) {
  console.log("Bucket data:", result.bucket);

  // Access stored values
  const token = result.bucket.sessionToken;
  const isLoggedIn = result.bucket.loggedIn;
} else {
  console.error("Failed to get bucket:", result.error);
}

Check if a session exists before logging in

TypeScript

const result = await agent.utils.bucket.get();

if (result.success && result.bucket.sessionToken) {
  console.log("Reusing existing session");
  // Skip login, use stored session
} else {
  console.log("No session found, performing login...");
  // Perform login flow
}

set()

TypeScript

set(data: Partial<Bucket>): Promise<{ success: false; error: string } | { success: true; bucket: Bucket }>

Merges the provided data into the existing bucket for this device+job combination. New keys are added and existing keys are overwritten. Keys not included in the provided data are preserved. If a bucket schema is defined on the automation, the merged data is validated against it.

Parameters

Name	Type	Description
`data`	Partial<Bucket>	Object containing the key-value pairs to merge into the bucket. Existing keys not present in this object are preserved.

Returns

{ success: true; bucket: Bucket } | { success: false; error: string }The full merged bucket data on success, or an error message

Examples

Store a session token after login

TypeScript

// After successful login, persist the session
const result = await agent.utils.bucket.set({
  sessionToken: "abc123xyz",
  loggedIn: true,
  loginTimestamp: Date.now(),
});

if (result.success) {
  console.log("Session saved:", result.bucket);
}

Merge additional data (existing keys are preserved)

TypeScript

// First call: store login info
await agent.utils.bucket.set({
  sessionToken: "abc123",
  loggedIn: true,
});

// Second call: add more data without losing sessionToken or loggedIn
await agent.utils.bucket.set({
  lastChecked: Date.now(),
  itemsProcessed: 5,
});

// Bucket now contains all four keys:
// { sessionToken, loggedIn, lastChecked, itemsProcessed }

Overwrite a specific key

TypeScript

// Update just the session token (other keys are preserved)
await agent.utils.bucket.set({
  sessionToken: "newToken456",
});

Bucket Schema

You can optionally define a bucket schema in the project editor under the Inputs tab. When a schema is defined:

The Bucket type is generated with the correct fields, giving you autocomplete and type checking
Data passed to set() is validated against the schema on the server

Typical Usage Pattern

TypeScript

// At the start of automation: check for existing state
const bucket = await agent.utils.bucket.get();

if (bucket.success && bucket.bucket.loggedIn) {
  // Resume from previous session
  console.log("Resuming with token:", bucket.bucket.sessionToken);
} else {
  // Fresh start - perform login
  const token = await performLogin();

  // Save state for next iteration
  await agent.utils.bucket.set({
    sessionToken: token,
    loggedIn: true,
  });
}

See also: Device Bucket for storage scoped to the device only (persists across all jobs and automations).