Skip to main content
Version: Next

ActorClient

Client for managing a specific Actor.

Provides methods to start, call, build, update, and delete an Actor, as well as manage its versions, builds, runs, and webhooks.

@example
const client = new ApifyClient({ token: 'my-token' });
const actorClient = client.actor('my-actor-id');

// Start an Actor
const run = await actorClient.start(input, { memory: 256 });

// Call an Actor and wait for it to finish
const finishedRun = await actorClient.call({ url: 'https://example.com' });
@see

https://docs.apify.com/platform/actors

Hierarchy

  • ResourceClient
    • ActorClient

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

build

  • build(versionNumber, options): Promise<Build>

  • Builds the Actor.

    Creates a new build of the specified Actor version. The build compiles the Actor's source code, installs dependencies, and prepares it for execution.

    @see

    https://docs.apify.com/api/v2/act-builds-post

    @example
    // Start a build and return immediately
    const build = await client.actor('my-actor').build('0.1');
    console.log(`Build ${build.id} started with status: ${build.status}`);

    // Build and wait up to 120 seconds for it to finish
    const build = await client.actor('my-actor').build('0.1', {
      waitForFinish: 120,
      tag: 'latest',
      useCache: true
    });

    Parameters

    • versionNumber: string

      Version number or tag to build (e.g., '0.1', '0.2', 'latest')

    • options: ActorBuildOptions = {}

      Build configuration options

    Returns Promise<Build>

    The Build object with status and build details

builds

call

  • Starts the Actor and waits for it to finish before returning the Run object.

    This is a convenience method that starts the Actor run and waits for its completion by polling the run status. It optionally streams logs to the console or a custom Log instance. By default, it waits indefinitely unless the waitSecs option is provided.

    @see

    https://docs.apify.com/api/v2/act-runs-post

    @example
    // Run an Actor and wait for it to finish
    const run = await client.actor('my-actor').call({ url: 'https://example.com' });
    console.log(`Run finished with status: ${run.status}`);
    console.log(`Dataset ID: ${run.defaultDatasetId}`);

    // Run with a timeout and log streaming to console
    const run = await client.actor('my-actor').call(
      { url: 'https://example.com' },
      { waitSecs: 300, log: 'default' }
    );

    // Run with custom log instance
    import { Log } from '@apify/log';
    const log = new Log({ prefix: 'My Actor' });
    const run = await client.actor('my-actor').call({ url: 'https://example.com' }, { log });

    Parameters

    • optionalinput: unknown

      Input for the Actor. Can be any JSON-serializable value (object, array, string, number). If contentType is specified in options, input should be a string or Buffer.

    • options: ActorCallOptions = {}

      Run configuration options (extends all options from start)

    Returns Promise<ActorRun>

    The finished Actor run object with final status (SUCCEEDED, FAILED, ABORTED, or TIMED-OUT)

defaultBuild

delete

  • delete(): Promise<void>

get

  • get(): Promise<undefined | Actor>

lastRun

  • Returns a client for the last run of this Actor.

    Provides access to the most recent Actor run, optionally filtered by status or origin.

    @see

    https://docs.apify.com/api/v2/act-runs-last-get

    @example
    // Get the last successful run
    const lastRun = await client.actor('my-actor').lastRun({ status: 'SUCCEEDED' }).get();

    Parameters

    Returns RunClient

    A client for the last run

runs

start

  • start(input, options): Promise<ActorRun>

  • Starts the Actor and immediately returns the Run object.

    The Actor run can be configured with optional input and various options. The run starts asynchronously and this method returns immediately without waiting for completion. Use the call method if you want to wait for the Actor to finish.

    @see

    https://docs.apify.com/api/v2/act-runs-post

    @example
    // Start Actor with simple input
    const run = await client.actor('my-actor').start({ url: 'https://example.com' });
    console.log(`Run started with ID: ${run.id}, status: ${run.status}`);

    // Start Actor with specific build and memory
    const run = await client.actor('my-actor').start(
      { url: 'https://example.com' },
      { build: '0.1.2', memory: 512, timeout: 300 }
    );

    Parameters

    • optionalinput: unknown

      Input for the Actor. Can be any JSON-serializable value (object, array, string, number). If contentType is specified in options, input should be a string or Buffer.

    • options: ActorStartOptions = {}

      Run configuration options

    Returns Promise<ActorRun>

    The Actor run object with status, usage, and storage IDs

update

  • update(newFields): Promise<Actor>

  • Updates the Actor with specified fields.

    @see

    https://docs.apify.com/api/v2/act-put

    Parameters

    • newFields: Partial<Pick<Actor, name | description | isPublic | isDeprecated | seoTitle | seoDescription | title | restartOnError | versions | categories | defaultRunOptions | actorStandby>>

      Fields to update in the Actor

    Returns Promise<Actor>

    The updated Actor object

version

versions

webhooks

Page Options