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.

Hierarchy

  • ResourceClient
    • ActorClient
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 more at https://docs.apify.com/platform/actors

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.

    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

    // 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
    });

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

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.

    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)

    // 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 });

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

defaultBuild

  • Returns a client for the default build of this Actor.

    Makes an API call to resolve the Actor's default build, then returns a BuildClient for that build. Use the returned client to get build details, wait for the build to finish, or access its logs.

    Parameters

    Returns Promise<BuildClient>

    A client for the default build

    // Get the default build client, then fetch build details
    const buildClient = await client.actor('my-actor').defaultBuild();
    const build = await buildClient.get();
    console.log(`Default build status: ${build.status}`);

    // Wait up to 60 seconds for the default build to finish
    const buildClient = await client.actor('my-actor').defaultBuild({ waitForFinish: 60 });
    const build = await buildClient.get();

    See more at https://docs.apify.com/api/v2/act-build-default-get

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.

    Parameters

    Returns RunClient

    A client for the last run

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

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

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.

    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

    // 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 }
    );

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

update

  • update(newFields): Promise<Actor>

  • Updates the Actor with specified fields.

    Parameters

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

      Fields to update in the Actor

    Returns Promise<Actor>

    The updated Actor object

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

version

versions

webhooks

Page Options