Connection
- Authentication: API key (Personal API token).
Sign in at console.apify.com → Settings → API & Integrations → Personal API tokens → copy the token (starts with apify_api_). Toggle “Limit token permissions” to scope it to the Actors and storages the agent needs.See Apify’s documentation.
Read actions (11)
| Action | Description |
|---|---|
get_actor | Retrieve a single Actor, including its default run options and the input schema its runs expect. actorId is either the Actor ID or “username |
get_current_user | Get the account the API token belongs to (username, plan, usage limits). Use it to check the connection. |
get_dataset_items | Read the items of a dataset as JSON — this is where an Actor run’s results live. datasetId is the dataset ID or “username~dataset-name”; after a run, take it from get_run’s defaultDatasetId. Filters: limit (integer — no limit by default, always set one on large datasets), offset (integer), fields (string — comma-separated list of item fields to keep), clean (boolean — drop empty items and hidden fields), desc (boolean — reverse order). |
get_key_value_store_record | Read one record of a key-value store — typically a run’s INPUT or OUTPUT. storeId is the store ID or “username~store-name” (after a run, get_run’s defaultKeyValueStoreId); recordKey is the record key, e.g. “INPUT”. Only JSON records are usable here: a record holding an image, a PDF or any other binary payload cannot be returned. |
get_run | Retrieve one run: its status, timings, and the storage IDs it writes to (defaultDatasetId, defaultKeyValueStoreId). Poll this after run_actor, then read the results with get_dataset_items on defaultDatasetId. |
list_actor_runs | List the runs of one Actor, newest first when desc is set. actorId is the Actor ID or “username~actor-name”. Filters: status (one of READY, RUNNING, SUCCEEDED, FAILED, TIMING-OUT, TIMED-OUT, ABORTING, ABORTED), limit (integer 1-1000), offset (integer), desc (boolean). |
list_actors | List Actors accessible to the account. Filters: my (boolean — only Actors owned by the account), limit (integer 1-1000), offset (integer), desc (boolean — newest first). |
list_datasets | List the account’s datasets. Filters: limit (integer 1-1000), offset (integer), desc (boolean — newest first), unnamed (boolean — include the unnamed datasets created by runs, which are hidden by default). |
list_runs | List the account’s runs across all Actors. Filters: status (one of READY, RUNNING, SUCCEEDED, FAILED, TIMING-OUT, TIMED-OUT, ABORTING, ABORTED), limit (integer 1-1000), offset (integer), desc (boolean — newest first). |
list_tasks | List the account’s saved tasks (an Actor plus a stored input). Filters: limit (integer 1-1000), offset (integer), desc (boolean — newest first). |
search_store | Search Apify Store for public Actors to run. Filters: search (string — matches title, name, description, username and readme), category (string), limit (integer 1-1000), offset (integer). Returns each Actor’s “username/name”, which converts to the actorId “username~name”. |
Write actions (4)
| Action | Description |
|---|---|
abort_run | Abort a running Actor run. Arguments: runId (string, required — the run id returned by run_actor or list_runs), gracefully (boolean, optional — when true the run is asked to persist its state and is force-stopped after 30 seconds; only Actors that handle the aborting event benefit from it). |
run_actor | Start an Actor run. Asynchronous: it returns the run object immediately (status READY or RUNNING), it does NOT wait for results — poll get_run with the returned id, then read get_dataset_items on the run’s defaultDatasetId. Consumes the account’s Apify credits. Arguments: actorId (string, required — Actor ID or “username~actor-name”), input (object, optional — the Actor’s own INPUT, sent as the JSON request body; its shape is defined by that Actor, read it with get_actor, e.g. {“startUrls”:[{“url”:“https://example.com”}],“maxRequestsPerCrawl”:10}), timeout (integer, optional — run timeout in seconds, 0 means no timeout), memory (integer, optional — memory limit in megabytes, a power of 2, minimum 128), build (string, optional — build tag or build number to run, defaults to the Actor’s configured build, usually “latest”), maxItems (integer, optional — caps the number of dataset items charged for pay-per-result Actors). |
run_actor_sync_get_dataset_items | Run an Actor and wait for it, returning its dataset items directly (JSON). The connection is held open until the run finishes: if it exceeds 300 seconds the API answers 408 Request Timeout and nothing is returned — use run_actor + get_run + get_dataset_items for anything longer. Consumes the account’s Apify credits. Arguments: actorId (string, required — Actor ID or “username~actor-name”), input (object, optional — the Actor’s own INPUT, sent as the JSON request body; read its shape with get_actor), timeout (integer, optional — run timeout in seconds, keep it at 300 or below), memory (integer, optional — memory limit in megabytes, a power of 2, minimum 128), build (string, optional — build tag or build number), maxItems (integer, optional — caps the dataset items charged for pay-per-result Actors), limit (integer, optional — maximum number of items returned), fields (string, optional — comma-separated list of item fields to keep), clean (boolean, optional — drop empty items and hidden fields). |
run_task | Start a run of a saved task. Asynchronous like run_actor: poll get_run, then read get_dataset_items on the run’s defaultDatasetId. Consumes the account’s Apify credits. Arguments: actorTaskId (string, required — task id or “username~task-name”, from list_tasks), input (object, optional — overrides the task’s stored input for this run only, sent as the JSON request body), timeout (integer, optional — run timeout in seconds), memory (integer, optional — memory limit in megabytes, a power of 2, minimum 128), build (string, optional — build tag or build number). |