> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# tool_apify

A RocketRide tool node for an agent that needs to run an Apify Actor or retrieve a dataset's items, with per-run item, time, and cost bounds.

## About Apify

Apify is the external service this node accesses through its Python client. Its Actor runs can produce a default dataset, and this node can also read a dataset that already exists.

## What it does

Use this node when an agent needs Actor-produced structured items or an existing Apify dataset. It exposes agent tools only—there are no pipeline lanes—and waits for an Actor run before reading its default dataset. Pick it over a general web or code-execution tool when the work is already packaged as an Apify Actor or dataset.

## As a tool

The registered prefix is `apify`, so the agent sees `apify.run_actor` and `apify.get_dataset_items`.

| Function | Description |
|---|---|
| `apify.run_actor` | Runs an Actor to completion, then reads items from its default dataset. |
| `apify.get_dataset_items` | Reads items from an existing dataset. |

### `apify.run_actor`

`actor_id` is required and may be an Actor ID or name. `run_input` is an optional object passed directly to that Actor, so its shape depends on the chosen Actor. `limit` is optional and is clamped to the configured item cap. The result contains `success`, `dataset_id`, `count`, and `items`; a run without a default dataset succeeds with an empty dataset ID and item list. Invalid input raises an error, and client errors from the Actor or dataset request are surfaced as tool failures.

### `apify.get_dataset_items`

`dataset_id` is required; `limit` is optional and uses the same configured cap. The result contains `success`, `count`, and `items`. A missing dataset ID raises an error, and client request failures are surfaced rather than represented as an empty result.

## Configuration

Set the API token first. The remaining settings are guardrails for agent-selected Actors; start with their defaults and increase them only when a known Actor needs more capacity.

### Max Items

This is the upper bound for items returned by either tool and defaults to 100. A per-call `limit` can reduce the result set but can never exceed this value; invalid or omitted call limits use the cap. Raise it when the agent needs a larger complete result set, and keep it small when sending results into a limited agent context. Invalid or non-positive configuration falls back to 100.

### Run Timeout (seconds)

This setting bounds both the Actor's run timeout and how long the client waits for it, defaulting to 120 seconds. Increase it for an Actor that legitimately takes longer to finish; leave it conservative for agent-chosen work so a stuck run cannot hold the pipeline indefinitely. Invalid or non-positive configuration falls back to 120.

### Max Cost (USD)

This value is passed as the per-run total-charge limit for pay-per-event Actors and defaults to 1. Increase it only after establishing the expected cost of the specific Actor; the limit applies to `run_actor`, not dataset reads. A value that cannot be parsed as a decimal falls back to 1.

## Authentication

Provide an Apify API token in **API Token**. The node creates its client at pipeline startup and fails to start when the configured token is empty.

## Upstream docs

- [Apify documentation](https://docs.apify.com/)

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_apify.apikey` | `string` | **API Token**<br/>Apify API token | `""` |
| `tool_apify.max_cost_usd` | `number` | **Max Cost (USD)**<br/>Spend limit per run for pay-per-event Actors. | `1` |
| `tool_apify.max_items` | `integer` | **Max Items**<br/>Upper cap on items returned per call (agent requests are clamped to this). | `100` |
| `tool_apify.run_timeout_secs` | `integer` | **Run Timeout (seconds)**<br/>Max seconds an Actor run may take before it is stopped. | `120` |

## Dependencies

- `apify-client` `>=3,<4`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_apify)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
