Cloudflare KV icon

Cloudflare KV

Store and retrieve data from Cloudflare Workers KV.
Join our community

Actions9

Overview

This node integrates with Cloudflare Workers KV, a globally distributed key-value storage system. It allows users to manage namespaces and perform various operations on key-value pairs within those namespaces. The "List Keys" operation specifically retrieves keys stored in a given namespace, optionally filtered by a prefix, and supports pagination.

Common scenarios include:

  • Retrieving all or filtered keys from a specific KV namespace for data inspection or processing.
  • Paginating through large sets of keys to handle them in batches.
  • Using the prefix filter to narrow down keys related to a particular category or feature.

Practical example:

  • A user wants to list all keys starting with "user_" in their "session-data" namespace to analyze active sessions.

Properties

Name Meaning
Namespace ID The ID of the KV namespace from which to list keys.
Prefix (Optional) Only return keys that begin with this prefix.
Limit Maximum number of results to return. Must be at least 1. Defaults to 50.
Cursor (Optional) Cursor string for pagination to continue listing keys from a previous request.

Output

The output JSON contains the response from the Cloudflare API listing keys in the specified namespace. It includes:

  • result: An array of key objects, each typically containing:
    • name: The key name.
    • expiration: (optional) Expiration timestamp if set.
    • metadata: (optional) Metadata associated with the key.
  • list_complete: Boolean indicating if all keys have been returned.
  • cursor: A cursor string to be used for fetching the next page of results if list_complete is false.

Example output structure:

{
  "result": [
    {
      "name": "exampleKey1",
      "expiration": 1735689600,
      "metadata": {}
    },
    {
      "name": "exampleKey2"
    }
  ],
  "list_complete": false,
  "cursor": "eyJjdXJzb3IiOiIxMjM0NSJ9"
}

No binary data is output by this operation.

Dependencies

  • Requires a valid Cloudflare API authentication token with permissions to access the account's KV namespaces.
  • The node expects credentials configured in n8n for authenticating requests to the Cloudflare API.
  • Network connectivity to Cloudflare's API endpoint.

Troubleshooting

  • Common issues:

    • Invalid or missing namespace ID will cause the API call to fail.
    • Insufficient API permissions or invalid API token will result in authorization errors.
    • Providing an invalid cursor string may cause pagination errors.
    • Exceeding the limit parameter beyond allowed maximums might cause API rejections.

  • Error messages:

    • "Key not found": Not applicable here but common in other operations; means the requested key does not exist.
    • HTTP 401/403 errors: Check API token validity and permissions.
    • HTTP 404 errors: Usually indicate the namespace ID does not exist.

  • Resolution tips:

    • Verify the namespace ID is correct and exists in your Cloudflare account.
    • Ensure the API token has appropriate scopes for KV operations.
    • Use the cursor returned from previous calls for pagination rather than arbitrary strings.
    • Keep the limit within reasonable bounds (default 50).

Links and References

Discussion