Skip to main content
Version: Next

RunClient

Sub-client for managing a specific Actor run.

Provides methods to manage a specific Actor run, e.g. get it, update it, abort it, or wait for it to finish. Obtain an instance via an appropriate method on the ApifyClient class.

Hierarchy

Index

Methods

Properties

Methods

__init__

  • __init__(*, base_url, public_base_url, http_client, resource_path, client_registry, resource_id, params, api_base_url): None

  • Initialize the resource client.

    Parameters

    • keyword-onlybase_url: str

      API base URL.

    • keyword-onlypublic_base_url: str

      Public CDN base URL.

    • keyword-onlyhttp_client: HttpClient

      HTTP client for making requests.

    • keyword-onlyresource_path: str

      Resource endpoint path (e.g., 'actors', 'datasets').

    • keyword-onlyclient_registry: ClientRegistry

      Bundle of client classes for dependency injection.

    • optionalkeyword-onlyresource_id: str | None = None

      Optional resource ID for single-resource clients.

    • optionalkeyword-onlyparams: dict | None = None

      Optional default parameters for all requests.

    • optionalkeyword-onlyapi_base_url: str | None = None

      Base URL of the API itself, for clients of top-level resources. Defaults to base_url.

    Returns None

abort

  • abort(*, gracefully, timeout): Run

  • Abort the Actor run which is starting or currently running and return its details.

    https://docs.apify.com/api/v2#/reference/actor-runs/abort-run/abort-run

    Parameters

    • optionalkeyword-onlygracefully: bool | None = None

      If True, the Actor run will abort gracefully. It will send aborting and persistStates events into the run and force-stop the run after 30 seconds. It is helpful in cases where you plan to resurrect the run later.

    • optionalkeyword-onlytimeout: Timeout = 'medium'

      Timeout for the API HTTP request.

    Returns Run

    The data of the aborted Actor run.

charge

  • charge(event_name, *, count, idempotency_key, timeout): None

  • Charge for an event of a Pay-Per-Event Actor run.

    https://docs.apify.com/api/v2#/reference/actor-runs/charge-events-in-run

    Parameters

    • event_name: str

      The name of the event to charge for.

    • optionalkeyword-onlycount: int = 1

      The number of events to charge.

    • optionalkeyword-onlyidempotency_key: str | None = None

      A unique key to ensure idempotent charging. If not provided, one will be auto-generated.

    • optionalkeyword-onlytimeout: Timeout = 'short'

      Timeout for the API HTTP request.

    Returns None

dataset

delete

  • delete(*, timeout): None

get

  • get(*, timeout): Run | None

get_status_message_watcher

  • Get StatusMessageWatcher instance that can be used to redirect status and status messages to logs.

    StatusMessageWatcher can be explicitly started and stopped or used as a context manager.

    Parameters

    • optionalkeyword-onlyto_logger: logging.Logger | None = None

      Logger used for logging the status and status messages. If not provided, a new logger is created.

    • optionalkeyword-onlycheck_period: timedelta = timedelta(seconds=1)

      The period with which the status message will be polled.

    • optionalkeyword-onlytimeout: Timeout = 'long'

      Timeout for the API HTTP request.

    Returns StatusMessageWatcher

    StatusMessageWatcher instance.

get_streamed_log

  • get_streamed_log(to_logger, *, from_start, timeout): StreamedLog

  • Get StreamedLog instance that can be used to redirect logs.

    StreamedLog can be explicitly started and stopped or used as a context manager.

    Parameters

    • optionalto_logger: logging.Logger | None = None

      Logger used for logging the redirected messages. If not provided, a new logger is created

    • optionalkeyword-onlyfrom_start: bool = True

      If True, all logs from the start of the Actor run will be redirected. If False, only newly arrived logs will be redirected. This can be useful for redirecting only a small portion of relevant logs for long-running Actors in stand-by.

    • optionalkeyword-onlytimeout: Timeout = 'long'

      Timeout for the API HTTP request.

    Returns StreamedLog

    StreamedLog instance for redirected logs.

iterate_dataset_items

  • iterate_dataset_items(*, offset, limit, clean, fields, omit, unwind, skip_empty, skip_hidden, chunk_size, poll_interval, timeout): Iterator[dict]

  • Iterate 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 item_count and then waits up to poll_interval 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 item_count, so it covers exactly the rows it asks for, whatever the filters or unwind do to the items. item_count 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 last_run() client, the iterator sticks to the run that its first request resolves to.

    https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items

    Parameters

    • optionalkeyword-onlyoffset: int | None = None

      Number of items that should be skipped at the start. The default value is 0.

    • optionalkeyword-onlylimit: int | None = None

      Maximum number of dataset rows to scan. Fewer items are yielded when filters drop some, more when unwind splits a row into several. By default there is no limit.

    • optionalkeyword-onlyclean: bool | None = None

      If True, returns only non-empty items and skips hidden fields (i.e. fields starting with the # character). The clean parameter is just a shortcut for skip_hidden=True and skip_empty=True parameters.

    • optionalkeyword-onlyfields: list[str] | None = None

      A list of fields which should be picked from the items, only these fields will remain in the resulting record objects.

    • optionalkeyword-onlyomit: list[str] | None = None

      A list of fields which should be omitted from the items.

    • optionalkeyword-onlyunwind: list[str] | None = None

      A list of fields which should be unwound, in order which they should be processed. Each field should be either an array or an object. If the field is an array then every element of the array will become a separate record and merged with parent object. If the unwound field is an object then it is merged with the parent object.

    • optionalkeyword-onlyskip_empty: bool | None = None

      If True, then empty items are skipped from the output.

    • optionalkeyword-onlyskip_hidden: bool | None = None

      If True, then hidden fields are skipped from the output, i.e. fields starting with the # character.

    • optionalkeyword-onlychunk_size: int | None = None

      Maximum number of dataset rows requested per API call.

    • optionalkeyword-onlypoll_interval: timedelta = timedelta(seconds=5)

      How long to wait for the run to finish between polls.

    • optionalkeyword-onlytimeout: Timeout = 'long'

      Timeout for each API HTTP request.

    Returns Iterator[dict]

key_value_store

log

metamorph

  • metamorph(*, target_actor_id, target_actor_build, run_input, content_type, timeout): Run

  • Transform an Actor run into a run of another Actor with a new input.

    https://docs.apify.com/api/v2#/reference/actor-runs/metamorph-run/metamorph-run

    Parameters

    • keyword-onlytarget_actor_id: str

      ID of the target Actor that the run should be transformed into.

    • optionalkeyword-onlytarget_actor_build: str | None = None

      The build of the target Actor. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the target Actor (typically the latest build).

    • optionalkeyword-onlyrun_input: Any = None

      The input to pass to the new run. Accepts the same values as KeyValueStoreClient.set_record, including an io.IOBase stream such as an open file, an iterable of byte chunks, or a streamed HttpResponse, which are uploaded in chunks without being held in memory. Streaming is experimental, and its behavior may change in future versions.

    • optionalkeyword-onlycontent_type: str | None = None

      The content type of the input.

    • optionalkeyword-onlytimeout: Timeout = 'medium'

      Timeout for the API HTTP request.

    Returns Run

    The Actor run data.

reboot

  • reboot(*, timeout): Run

request_queue

resurrect

  • resurrect(*, build, memory_mbytes, run_timeout, max_items, max_total_charge_usd, restart_on_error, timeout): Run

  • Resurrect a finished Actor run.

    Only finished runs, i.e. runs with status SUCCEEDED, FAILED, ABORTED and TIMED-OUT can be resurrected. Run status will be updated to RUNNING and its container will be restarted with the same default storages.

    https://docs.apify.com/api/v2#/reference/actor-runs/resurrect-run/resurrect-run

    Parameters

    • optionalkeyword-onlybuild: str | None = None

      Which Actor build the resurrected run should use. It can be either a build tag or build number. By default, the resurrected run uses the same build as before.

    • optionalkeyword-onlymemory_mbytes: int | None = None

      New memory limit for the resurrected run, in megabytes. By default, the resurrected run uses the same memory limit as before.

    • optionalkeyword-onlyrun_timeout: timedelta | None = None

      New timeout for the resurrected run. By default, the resurrected run uses the same timeout as before.

    • optionalkeyword-onlymax_items: int | None = None

      Maximum number of items that the resurrected pay-per-result run will return. By default, the resurrected run uses the same limit as before. Limit can be only increased.

    • optionalkeyword-onlymax_total_charge_usd: Decimal | None = None

      Maximum cost for the resurrected pay-per-event run in USD. By default, the resurrected run uses the same limit as before. Limit can be only increased.

    • optionalkeyword-onlyrestart_on_error: bool | None = None

      Determines whether the resurrected run will be restarted if it fails. By default, the resurrected run uses the same setting as before.

    • optionalkeyword-onlytimeout: Timeout = 'medium'

      Timeout for the API HTTP request.

    Returns Run

    The Actor run data.

update

  • update(*, status_message, is_status_message_terminal, general_access, timeout): Run

  • Update the run with the specified fields.

    https://docs.apify.com/api/v2#/reference/actor-runs/run-object/update-run

    Parameters

    • optionalkeyword-onlystatus_message: str | None = None

      The new status message for the run.

    • optionalkeyword-onlyis_status_message_terminal: bool | None = None

      Set this flag to True if this is the final status message of the Actor run.

    • optionalkeyword-onlygeneral_access: GeneralAccess | None = None

      Determines how others can access the run and its storages.

    • optionalkeyword-onlytimeout: Timeout = 'short'

      Timeout for the API HTTP request.

    Returns Run

    The updated run.

wait_for_finish

  • wait_for_finish(*, wait_duration, timeout): Run | None

  • Wait synchronously until the run finishes or the server times out.

    Parameters

    • optionalkeyword-onlywait_duration: timedelta | None = None

      How long does the client wait for run to finish. None for indefinite.

    • optionalkeyword-onlytimeout: Timeout = 'no_timeout'

      Timeout for the API HTTP request.

    Returns Run | None

    The Actor run data. If the status on the object is not one of the terminal statuses (SUCCEEDED, FAILED, TIMED-OUT, ABORTED), then the run has not yet finished.

Properties

resource_id

resource_id: str | None

Get the resource ID.

Page Options