Input & output

An Actor reads its input once at start, writes results to its default dataset, and keeps files and state in its default key-value store. This page covers the Actor shortcuts for those three jobs.

Input

Actor.getInput<T>()

getInput() returns Promise<T | null> and requires Actor.init(). It looks for input in this order:

1. If ACTOR_METAMORPH_COUNT is greater than 0, the INPUT-METAMORPH-{count} record of the default key-value store.
2. ACTOR_INPUT, decoded as base64 JSON, then as plain JSON.
3. Only when ACTOR_INPUT is unset: the default key-value store record named by ACTOR_INPUT_KEY (normally INPUT).

On the platform, ACTOR_INPUT is always set when the run has input, and the same input is stored in the INPUT record. Locally, scrapely run sets ACTOR_INPUT from -i, -f, or storage/key_value_stores/default/INPUT.json.

type Input = { startUrls: string[]; maxPages?: number };

const input = await Actor.getInput<Input>();
if (input === null) throw new Error('No input was provided');

Secret input fields (isSecret in the input schema) arrive already decrypted: the platform decrypts them before the container starts, and the run's own token reads the INPUT record decrypted. See Secret input fields. The SDK only decrypts values itself if APIFY_INPUT_SECRETS_PRIVATE_KEY_FILE and APIFY_INPUT_SECRETS_PRIVATE_KEY_PASSPHRASE are set, which platform runs don't do.

Actor.getInputOrThrow<T>()

const input = await Actor.getInputOrThrow<Input>();

Throws Input does not exist when getInput() returns null or undefined. It doesn't validate the shape; check required fields yourself before doing expensive work.

Actor.input

Actor.input is a synchronous getter that parses ACTOR_INPUT (base64 JSON, then plain JSON) on first access and caches the result. It returns undefined when ACTOR_INPUT is unset or invalid, doesn't read the key-value store, and doesn't need init(). Prefer getInput().

Output and key-value records

Actor.pushData()

pushData(item) writes one object or an array of objects to the default dataset. Each object must serialize to JSON smaller than 9 MB.

await Actor.pushData({ url: 'https://example.com', title: 'Example' });
await Actor.pushData([
    { page: 1, value: 'a' },
    { page: 2, value: 'b' },
]);

Pass an event name to charge a pay-per-event event once per item:

const result = await Actor.pushData(items, 'page-scraped');
if (result.eventChargeLimitReached) {
    await Actor.exit('Charge limit reached');
}

With an event name, pushData() returns a ChargeResult. It charges before writing and only writes as many items as the run's remaining budget (maxTotalChargeUsd) covers, so items beyond the cap are dropped, not written for free. On an Actor that isn't priced per event, the items are written and nothing is charged. See Charging.

If the write fails after the charge was accepted and the SDK knows nothing was stored (the API returned an error, or the connection was never made), pushData() voids the charge and rethrows. A timeout after sending keeps the charge, since the items may have been stored. Voids that can't be confirmed are retried before the next push and at exit.

On a pay-per-event Actor whose pricing includes the default dataset item event, every write to the default dataset is charged automatically, including writes made through Dataset or a crawler's pushData. In that case pushData() also returns a ChargeResult.

pushData() throws Cannot charge for synthetic event '<name>' manually if you pass apify-default-dataset-item or scrapely-default-dataset-item as the event name.

Actor.getValue() and Actor.setValue()

These read and write records of the default key-value store:

const state = await Actor.getValue<{ cursor: string }>('STATE');
await Actor.setValue('STATE', { cursor: 'next' });
await Actor.setValue('TEMPORARY', null); // deletes the record

getValue() returns null when the record doesn't exist. setValue() stores objects as JSON. Its options (RecordOptions):

await Actor.setValue('PAGE_HTML', '<h1>Hello</h1>', {
    contentType: 'text/html',
});

To work with other stores or list keys, open the store with Actor.openKeyValueStore() (see Storages & Crawlee). For how callers download datasets and records, see Results.