Skip to main content
Version: Next

KeyValueStoreClient

Client for managing a specific key-value store.

Key-value stores are used to store arbitrary data records or files. Each record is identified by a unique key and can contain any type of data. This client provides methods to get, set, and delete records, list keys, and manage the store.

@example
const client = new ApifyClient({ token: 'my-token' });
const storeClient = client.keyValueStore('my-store-id');

// Set a record
await storeClient.setRecord({
  key: 'OUTPUT',
  value: { foo: 'bar' },
  contentType: 'application/json'
});

// Get a record
const record = await storeClient.getRecord('OUTPUT');

// List all keys
const { items } = await storeClient.listKeys();
@see

https://docs.apify.com/platform/storage/key-value-store

Hierarchy

  • ResourceClient
    • KeyValueStoreClient

Index

Properties

Methods

Properties

inheritedapifyClient

apifyClient: ApifyClient

inheritedbaseUrl

baseUrl: string

inheritedhttpClient

httpClient: HttpClient

optionalinheritedid

id?: string

optionalinheritedparams

params?: Record<string, unknown>

inheritedpublicBaseUrl

publicBaseUrl: string

inheritedresourcePath

resourcePath: string

optionalinheritedsafeId

safeId?: string

inheritedurl

url: string

Methods

createKeysPublicUrl

  • createKeysPublicUrl(options): Promise<string>

  • Generates a public URL for accessing the list of keys in the key-value store.

    If the client has permission to access the key-value store's URL signing key, the URL will include a cryptographic signature which allows access without authentication.

    @example
    // Create a URL that expires in 1 hour
    const url = await client.keyValueStore('my-store').createKeysPublicUrl({
      expiresInSecs: 3600,
      prefix: 'image-'
    });
    console.log(`Share this URL: ${url}`);

    Parameters

    Returns Promise<string>

    A public URL string for accessing the keys list

delete

  • delete(): Promise<void>

deleteRecord

  • deleteRecord(key): Promise<void>

get

getRecord

  • You can use the buffer option to get the value in a Buffer (Node.js) or ArrayBuffer (browser) format. In Node.js (not in browser) you can also use the stream option to get a Readable stream.

    When the record does not exist, the function resolves to undefined. It does NOT resolve to a KeyValueStore record with an undefined value.

    @see

    https://docs.apify.com/api/v2/key-value-store-record-get

    Parameters

    • key: string

    Returns Promise<undefined | KeyValueStoreRecord<JsonValue>>

getRecordPublicUrl

  • getRecordPublicUrl(key): Promise<string>

  • Generates a public URL for accessing a specific record in the key-value store.

    If the client has permission to access the key-value store's URL signing key, the URL will include a cryptographic signature for authenticated access without requiring an API token.

    @example
    const url = await client.keyValueStore('my-store').getRecordPublicUrl('OUTPUT');
    console.log(`Public URL: ${url}`);
    // You can now share this URL or use it in a browser

    Parameters

    • key: string

      The record key

    Returns Promise<string>

    A public URL string for accessing the record

listKeys

  • Lists all keys in the key-value store.

    Returns a paginated list of all record keys in the store. Use pagination parameters to retrieve large lists efficiently.

    @see

    https://docs.apify.com/api/v2/key-value-store-keys-get

    @example
    // List all keys
    const { items, isTruncated } = await client.keyValueStore('my-store').listKeys();
    items.forEach(item => console.log(`${item.key}: ${item.size} bytes`));

    // List keys with prefix
    const { items } = await client.keyValueStore('my-store').listKeys({ prefix: 'user-' });

    // Paginate through all keys
    let exclusiveStartKey;
    do {
      const result = await client.keyValueStore('my-store').listKeys({
        limit: 100,
        exclusiveStartKey
      });
      // Process result.items...
      exclusiveStartKey = result.nextExclusiveStartKey;
    } while (result.isTruncated);

    Parameters

    Returns Promise<KeyValueClientListKeysResult> & AsyncIterable<KeyValueListItem, any, any>

    Object containing items array of key metadata, pagination info (count, limit, isTruncated, nextExclusiveStartKey)

recordExists

  • recordExists(key): Promise<boolean>

  • Tests whether a record with the given key exists in the key-value store without retrieving its value.

    This is more efficient than getRecord when you only need to check for existence.

    @see

    https://docs.apify.com/api/v2/key-value-store-record-get

    @example
    const exists = await client.keyValueStore('my-store').recordExists('OUTPUT');
    if (exists) {
      console.log('OUTPUT record exists');
    }

    Parameters

    • key: string

      The record key to check

    Returns Promise<boolean>

    true if the record exists, false if it does not

setRecord

  • setRecord(record, options): Promise<void>

  • Stores a record in the key-value store.

    The record value can be any JSON-serializable object, a string, or a Buffer/Stream. The content type is automatically determined based on the value type, but can be overridden using the contentType property.

    Note about streams: If the value is a stream object (has .pipe and .on methods), the upload cannot be retried on failure or follow redirects. For reliable uploads, buffer the entire stream into memory first.

    @see

    https://docs.apify.com/api/v2/key-value-store-record-put

    @example
    // Store JSON object
    await client.keyValueStore('my-store').setRecord({
      key: 'OUTPUT',
      value: { crawledUrls: 100, items: [...] }
    });

    // Store text
    await client.keyValueStore('my-store').setRecord({
      key: 'README',
      value: 'This is my readme text',
      contentType: 'text/plain'
    });

    // Store binary data
    const imageBuffer = await fetchImageBuffer();
    await client.keyValueStore('my-store').setRecord({
      key: 'screenshot.png',
      value: imageBuffer,
      contentType: 'image/png'
    });

    Parameters

    Returns Promise<void>

update

Page Options