Key-Value Storage Functions
A key-value bucket stores small values under string keys. Use it for state a flow needs to keep between runs — a cursor, a counter, a cached lookup, a per-customer setting. Five functions are available to a Function step:
Buckets are per-account. There is no delete function — remove a bucket or a key from the platform UI.
For anything larger than a small JSON document — a file, a PDF, an export — use Object Storage instead.
Names and limits
- Bucket names must match
[a-zA-Z0-9_-]+. No dots, no spaces. - Keys must match
[-/_=.a-zA-Z0-9]+and may not begin or end with a dot. A key built from user input needs sanitising first. ttlis in nanoseconds. It is a Go duration on the wire: one hour is3600000000000.historydefaults to 1 and caps at 64.
create-key-value-bucket
Creates a bucket. Creating one that already exists returns an error in the body rather than replacing it. Payload{"status_code": 409, "body": {"error": "..."}}.
put-kv-item
Writes a value. Writing an existing key overwrites it; the previous value is kept only if the bucket’shistory is above 1.
Payload
get-kv-bucket-item
Reads one key.Return the value as it is rather than re-serialising it. Defaults to
false — see the warning below.$.STEP_ID.body.body.value.
list-key-value-buckets
Lists every key-value bucket in the account. Takes no parameters — an empty payload{} is correct.
Returns
list-kv-bucket-items
Lists the keys in one bucket, with their values. A bucket holding anything sensitive should not be listed from a flow. Payloadvalue varies from row to row, and code reading a listing has to cope with both.
results_total counts the rows in this page, not the bucket. When a page is cut short the body also carries truncated: true and a next_cursor string; send that string back as cursor to continue. Treat the cursor as opaque.
Failure
Every function on this page catches its own errors and returns{"error": "<message>"}. That is a successful step — the run continues and the next step reads an object with an error key where it expected data.
If a later step depends on the read succeeding, branch on it:
failed to determine next steps.
See Building Reliable Flows for what a part-completed run leaves behind.
Related
Object Storage
For files and anything large
Streams
For an append-only history rather than a current value
Utilities
Secrets, encoding, templating, format conversion
Functions Overview
The full catalogue