Apify — key-value-store/getRecord

When to Use

Reading structured actor output: Many actors write their primary output to the OUTPUT key of the default key-value store as a structured JSON object (rather than a dataset). Use this node to retrieve that output after confirming run completion.
Screenshot retrieval: Actors using Playwright or Puppeteer often save full-page screenshots to the KV store under keys like screenshot or page-0.jpg. Retrieve the base64-encoded binary for display, storage, or email attachment workflows.
Actor input inspection: Every run's default KV store contains an INPUT record — the exact input the actor received. Read this for debugging, audit logging, or validating that the correct input was passed to a run.
Shared configuration blobs: When an actor uses a named KV store as a configuration source (e.g. a list of proxy configurations or a scraping ruleset), read the configuration record at workflow start before triggering actor runs.
Multi-format output handling: Actors may store results in different formats depending on their configuration — JSON for structured data, HTML for page captures, CSV as text. Use the contentType and isBinary output fields to route to format-specific processing nodes.

Content-Type handling: The Apify service layer branches on the HTTP Content-Type header returned by Apify:
• application/json → data is a parsed object (or array). isBinary: false.
• text/* (text/plain, text/html, text/csv) → data is a string. isBinary: false.
• All other types (image/*, application/pdf, etc.) → data is a base64-encoded string. isBinary: true.
Always check isBinary before processing data.

Configuration

Connection

Field	Required	Description
`credentialId`	Required	BizFirstAI credential ID holding the Apify API token.
`baseUrl`	Optional	Apify API base URL. Defaults to `https://api.apify.com`.

Operation

Field (config key)	Required	Description
`resource`	Required	Must be `"key-value-store"`.
`operation`	Required	Must be `"get-record"`.
`storeId`	Required	The Apify Key-Value Store ID. Obtain from `defaultKeyValueStoreId` in any run operation output, or from the Apify Console → Storage → Key-Value Stores. Supports BizFirst expressions.
`recordKey`	Required	The key identifying the record to retrieve. Case-sensitive string. Common built-in keys: `"INPUT"` (actor input), `"OUTPUT"` (actor output). Custom keys are actor-specific.

Sample Configuration

{
  "resource": "key-value-store",
  "operation": "get-record",
  "credentialId": "apify-prod-token",
  "storeId": "{{ $output.runPollNode.defaultKeyValueStoreId }}",
  "recordKey": "OUTPUT"
}

Validation Errors

Error	Cause
`API token is required`	`credentialId` / `apiToken` is missing or empty.
`Store ID is required`	`storeId` is missing or empty.
`Record Key is required`	`recordKey` is missing or empty.
`Invalid settings for key-value-store/get-record`	Internal type mismatch. Verify `resource` is `"key-value-store"` and `operation` is `"get-record"`.
`APIFY_ERROR` (error port)	Store ID or record key not found (404), API token lacks access, or a network error occurred.

Output

Success Port

Field	Type	Description
`storeId`	string	The KV store ID that was queried.
`recordKey`	string	The record key that was retrieved.
`contentType`	string	The Content-Type of the record as returned by Apify, e.g. `"application/json"`, `"text/plain"`, `"image/png"`.
`data`	any	The record content. Type depends on `contentType`: an object for JSON, a string for text, or a base64-encoded string for binary. Empty object (`{}`) if the record has no content.
`isBinary`	boolean	`true` when `data` is base64-encoded binary. `false` for JSON and text records. Always check this before processing `data`.

Error Port

Routes here when the store ID is not found, the record key does not exist in the store, authentication fails, or a network error occurs. Output contains errorCode ("APIFY_ERROR") and message.

Key not found: If the recordKey does not exist in the store, Apify returns a 404 and the node routes to the error port. This is a common occurrence when an actor did not write to a particular key (e.g. no OUTPUT key if the actor failed early). Always handle the error port to distinguish "key not found" from a connectivity issue.

Sample Output — JSON Record

{
  "storeId": "kvs_m7n8o9p0q1r2",
  "recordKey": "OUTPUT",
  "contentType": "application/json",
  "data": {
    "totalProducts": 1247,
    "successfulPages": 49,
    "failedPages": 1,
    "scrapeStartedAt": "2026-05-26T10:00:01.000Z",
    "scrapeFinishedAt": "2026-05-26T10:04:22.000Z",
    "averagePriceUsd": 89.42
  },
  "isBinary": false
}

Sample Output — Text Record

{
  "storeId": "kvs_m7n8o9p0q1r2",
  "recordKey": "page-content.html",
  "contentType": "text/html",
  "data": "Example Page...",
  "isBinary": false
}

Sample Output — Binary Record

{
  "storeId": "kvs_m7n8o9p0q1r2",
  "recordKey": "screenshot",
  "contentType": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAA...(base64 encoded)...AASUVORK5CYII=",
  "isBinary": true
}

Expression Reference

Expression	Returns
`{{ $output.apify.data }}`	Record content — object (JSON), string (text), or base64 string (binary).
`{{ $output.apify.isBinary }}`	Boolean — use in `IfCondition` to route binary vs non-binary handling.
`{{ $output.apify.contentType }}`	Content-Type string for format-specific routing.
`{{ $output.apify.recordKey }}`	Record key echoed from configuration.
`{{ $output.apify.data.totalProducts }}`	Field within a JSON `data` object (when `isBinary: false` and `contentType` is JSON).
`{{ $output.apify.storeId }}`	Store ID for audit or chained calls.

Node Policies & GuardRails

Policy	Recommendation	Severity
API token storage	Use `credentialId`; never embed raw tokens.	Critical
Binary check before processing	Always check `isBinary` before accessing `data` fields. Attempting to access JSON fields on a base64 string causes a null reference in downstream nodes.	Critical
Error port for missing keys	Always handle the error port. Many workflow patterns speculatively read optional KV store keys (e.g. `OUTPUT` may not exist if an actor failed). Missing key errors route here and should be treated as a data-not-available condition, not a fatal error.	High
KV store retention	Apify KV stores expire on the same schedule as datasets (7 days for free tier). Persist critical records to your own storage immediately after retrieval.	High
Binary size limits	Base64-encoded binary records can be very large (screenshots, full-page HTML). Verify the downstream node can handle the payload size before passing binary data through the workflow. Consider storing large binaries directly to S3 or equivalent storage.	Medium
Record key case sensitivity	`recordKey` is case-sensitive. `"OUTPUT"`, `"output"`, and `"Output"` are three different keys. Verify exact casing against actor documentation or console inspection.	Medium

Examples

Read Structured Actor Output — JSON OUTPUT Key

{
  "resource": "key-value-store",
  "operation": "get-record",
  "credentialId": "apify-prod-token",
  "storeId": "{{ $output.runPollNode.defaultKeyValueStoreId }}",
  "recordKey": "OUTPUT"
}
// Downstream IfCondition:
// isBinary === false && contentType === "application/json"
//   → process data as object
// else → route to error handler

After an async actor run is confirmed SUCCEEDED, reads the actor's structured output from the OUTPUT key. The data field contains the actor's result object — often a run summary, aggregated statistics, or a curated subset of the scraped data.

Screenshot Retrieval and Storage

{
  "resource": "key-value-store",
  "operation": "get-record",
  "credentialId": "apify-prod-token",
  "storeId": "{{ $output.runNode.defaultKeyValueStoreId }}",
  "recordKey": "screenshot"
}
// IfCondition: isBinary === true
//   → S3 upload node (decode base64, upload as image/png)
// else → log unexpected content type

Retrieves a Playwright screenshot saved by an actor. The isBinary: true output is detected by an IfCondition and routed to an S3 node that decodes the base64 string and stores the image file for display in a monitoring dashboard.

Actor Input Audit — Read INPUT Record

{
  "resource": "key-value-store",
  "operation": "get-record",
  "credentialId": "apify-audit-token",
  "storeId": "{{ $input.storeId }}",
  "recordKey": "INPUT"
}

For compliance auditing, retrieves the exact input that was passed to a historical actor run. The data object contains the actor's input JSON, which is serialized and written to an audit log table alongside the run ID, start time, and triggering workflow ID.