Skip to main content
Version: Next

RunClient

Client for managing a specific Actor run.

Provides methods to get run details, abort, metamorph, resurrect, wait for completion, and access the run's dataset, key-value store, request queue, and logs.

Hierarchy

  • ResourceClient
    • RunClient
const client = new ApifyClient({ token: 'my-token' });
const runClient = client.run('my-run-id');

// Get run details
const run = await runClient.get();

// Wait for the run to finish
const finishedRun = await runClient.waitForFinish();

// Access the run's dataset
const { items } = await runClient.dataset().listItems();

See more at https://docs.apify.com/platform/actors/running/runs-and-builds

Index

Properties

Methods

Properties

inheritedapifyClient

apifyClient: ApifyClient

inheritedbaseUrl

baseUrl: string

inheritedhttpClient

httpClient: HttpClient

optionalinheritedid

id?: string

optionalinheritedparams

params?: Record<string, unknown>

inheritedpublicBaseUrl

publicBaseUrl: string

Added in 2.17.0

inheritedresourcePath

resourcePath: string

optionalinheritedsafeId

safeId?: string

inheritedurl

url: string

Methods

abort

  • abort(options): Promise<Run>

  • Aborts the Actor run.

    Parameters

    Returns Promise<Run>

    The updated Run object with ABORTING or ABORTED status

    // Abort immediately
    await client.run('run-id').abort();

    // Abort gracefully (allows cleanup)
    await client.run('run-id').abort({ gracefully: true });

    See more at https://docs.apify.com/api/v2/actor-run-abort-post

charge

dataset

  • Returns a client for the default dataset of this Actor run.

    A 404 from this client throws an ApifyApiError, since the run itself may be what is missing.

    Returns DatasetClient<Record<string | number, unknown>>

    A client for accessing the run's default dataset

    // Access run's dataset
    const { items } = await client.run('run-id').dataset().listItems();

    See more at https://docs.apify.com/api/v2/actor-run-get

delete

  • delete(options): Promise<void>

get

  • get(options): Promise<undefined | Run>

  • Gets the Actor run object from the Apify API.

    Parameters

    Returns Promise<undefined | Run>

    The Run object, or undefined if it does not exist

    // Get run status immediately
    const run = await client.run('run-id').get();
    console.log(`Status: ${run.status}`);

    // Wait up to 60 seconds for run to finish
    const run = await client.run('run-id').get({ waitForFinish: 60 });

    See more at https://docs.apify.com/api/v2/actor-run-get

getStreamedLog

  • getStreamedLog(options): Promise<undefined | StreamedLog>

  • Get StreamedLog for convenient streaming of the run log and their redirection.

    Parameters

    Returns Promise<undefined | StreamedLog>

    Added in 2.20.0

iterateDatasetItems

  • iterateDatasetItems<Data>(options): AsyncGenerator<Data, void, undefined>

  • Iterates over the items of the run's default dataset while the run is still producing them.

    While the run has not finished, each poll yields the rows below the dataset's itemCount and then waits up to pollIntervalSecs for the run to finish, so the last rows are read as soon as it does. Each page is requested with a limit that ends at itemCount, so it covers exactly the rows it asks for, whatever the filters or unwind do to the items. itemCount lags a few seconds behind the pushed items, so once the run reaches a terminal status, the rows past it are read a page at a time until none are left, and the iterator returns. On a lastRun() client, the iterator sticks to the run that its first request resolves to.

    Parameters

    Returns AsyncGenerator<Data, void, undefined>

    An async iterable of the dataset items

    for await (const item of client.run('run-id').iterateDatasetItems()) {
        console.log(item);
    }

    See more at https://docs.apify.com/api/v2/dataset-items-get

keyValueStore

  • Returns a client for the default key-value store of this Actor run.

    get() and delete() throw an ApifyApiError on a 404, since the run itself may be what is missing. Record lookups such as getRecord() read a 404 as a missing record.

    Returns KeyValueStoreClient

    A client for accessing the run's default key-value store

    // Access run's key-value store
    const output = await client.run('run-id').keyValueStore().getRecord('OUTPUT');

    See more at https://docs.apify.com/api/v2/actor-run-get

log

  • Returns a client for accessing the log of this Actor run.

    A 404 from this client throws an ApifyApiError, since the run itself may be what is missing.

    Returns LogClient

    A client for accessing the run's log

    // Get run log
    const log = await client.run('run-id').log().get();
    console.log(log);

    See more at https://docs.apify.com/api/v2/actor-run-get

metamorph

  • metamorph(targetActorId, input, options): Promise<Run>

  • Transforms the Actor run into a run of another Actor (metamorph).

    This operation preserves the run ID, storages (dataset, key-value store, request queue), and resource allocation. The run effectively becomes a run of the target Actor with new input. This is useful for chaining Actor executions or implementing complex workflows.

    Parameters

    • targetActorId: string

      ID or username/name of the target Actor

    • optionalinput: ActorInput

      Input for the target Actor: an object or array serialized to JSON, or raw bytes sent as they are. Omit it to metamorph without input.

    • options: RunMetamorphOptions = {}

      Metamorph options

    Returns Promise<Run>

    The metamorphed Run object (same ID, but now running the target Actor)

    // Transform current run into another Actor
    const metamorphedRun = await client.run('original-run-id').metamorph(
      'target-actor-id',
      { url: 'https://example.com' }
    );
    console.log(`Run ${metamorphedRun.id} is now running ${metamorphedRun.actId}`);

    See more at https://docs.apify.com/api/v2/actor-run-metamorph-post

reboot

  • reboot(options): Promise<Run>

  • Reboots the Actor run.

    Rebooting restarts the Actor's Docker container while preserving the run ID and storages. This can be useful to recover from certain errors or to force the Actor to restart with a fresh environment.

    Parameters

    Returns Promise<Run>

    The updated Run object

    const run = await client.run('run-id').reboot();

    See more at https://docs.apify.com/api/v2/actor-run-reboot-post

    Added in 2.8.0

requestQueue

  • Returns a client for the default Request queue of this Actor run.

    get() and delete() throw an ApifyApiError on a 404, since the run itself may be what is missing. getRequest() reads a 404 as a missing request.

    Returns RequestQueueClient

    A client for accessing the run's default Request queue

    // Access run's Request queue
    const { items } = await client.run('run-id').requestQueue().listHead();

    See more at https://docs.apify.com/api/v2/actor-run-get

resurrect

  • resurrect(options): Promise<Run>

  • Resurrects a finished Actor run, starting it again with the same settings.

    This creates a new run with the same configuration as the original run. The original run's storages (dataset, key-value store, request queue) are preserved and reused.

    Parameters

    Returns Promise<Run>

    The new (resurrected) Run object

    // Resurrect a failed run with more memory
    const newRun = await client.run('failed-run-id').resurrect({ memory: 2048 });
    console.log(`New run started: ${newRun.id}`);

    See more at https://docs.apify.com/api/v2/post-resurrect-run

update

  • update(newFields, options): Promise<Run>

  • Updates the Actor run with specified fields.

    Parameters

    Returns Promise<Run>

    The updated Run object

    // Set a status message
    await client.run('run-id').update({
      statusMessage: 'Processing items: 50/100'
    });

    Added in 2.6.0

waitForFinish

  • waitForFinish(options): Promise<Run>

  • Waits for the Actor run to finish and returns the finished Run object.

    The promise resolves when the run reaches a terminal state (SUCCEEDED, FAILED, ABORTED, or TIMED-OUT). If waitSecs is provided and the timeout is reached, the promise resolves with the unfinished Run object (status will be RUNNING or READY). The promise is NOT rejected based on run status.

    Unlike the waitForFinish parameter in get, this method can wait indefinitely by polling the run status. It uses the waitForFinish parameter internally (max 60s per call) and continuously polls until the run finishes or the timeout is reached. Rejects with a NotFoundError if the run keeps returning 404 for 3 seconds.

    Parameters

    Returns Promise<Run>

    The Run object (finished or still running if the timeout was reached)

    // Wait indefinitely for run to finish
    const run = await client.run('run-id').waitForFinish();
    console.log(`Run finished with status: ${run.status}`);

    // Wait up to 5 minutes
    const run = await client.run('run-id').waitForFinish({ waitSecs: 300 });
    if (run.status === 'SUCCEEDED') {
      console.log('Run succeeded!');
    }
Page Options