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). |
Permissions
Every action above must be explicitly granted to an agent before it can be used. See Permissions for the grant model and Security for how credentials are protected.Last reviewed against the provider API: September 2026.