Retool Apify Integration - Run Actors & Return Data

Trigger Apify Actors or saved tasks from Retool, wait for completion when needed, and return one predictable JSON object that Retool can bind directly to tables, charts, forms, and workflows.

Why use this Actor?

Retool can call REST APIs directly, but every Apify workflow otherwise needs repeated glue logic for run creation, waiting, status handling, dataset retrieval, errors, and result normalization. This bridge packages that workflow into one reusable Actor.

Use cases

• Run an Apify Actor from a Retool button and pass form/table values as JSON input.
• Fill a Retool table with Apify dataset results after a synchronous run finishes.
• Start long-running workflows asynchronously and keep a Retool row ID in correlationId for later polling or webhook logic.

What it returns

Each bridge run emits one WORKFLOW_RESULT record and writes the same object to the default key-value store as OUTPUT.

Key fields include:

• status: SUCCESS, STARTED, TARGET_FAILED, TIMEOUT, or ERROR
• targetType, targetId
• runId, runStatus, statusMessage
• startedAt, finishedAt
• defaultDatasetId
• datasetItemCountReturned
• datasetItems (optional)
• runConsoleUrl, datasetConsoleUrl
• correlationId
• errorType, errorMessage

How it works

1. Retool starts this bridge Actor using the Apify API.
2. The bridge launches the requested Actor or task.
3. In sync mode it waits for a terminal status, then optionally retrieves the target's default dataset.
4. It normalizes the workflow into one stable JSON object.
5. In async mode it returns immediately with the downstream runId.

Minimal input

{
  "targetType": "actor",
  "targetId": "apify~hello-world",
  "targetInput": {},
  "mode": "sync"
}

Advanced input

{
  "targetType": "actor",
  "targetId": "your-user~your-actor",
  "targetInput": {
    "startUrls": [{"url": "https://example.com"}],
    "maxItems": 20
  },
  "mode": "sync",
  "waitTimeoutSeconds": 180,
  "includeDatasetItems": true,
  "datasetLimit": 100,
  "datasetFields": ["title", "url"],
  "cleanDataset": true,
  "correlationId": "retool-row-123"
}

Authentication and permissions

On Apify, the bridge first uses the scoped APIFY_TOKEN injected into the run. Limited-permission Actors can call other limited-permission Actors and obtain their results, so many public Actor workflows need no second token.

For a private Actor task or another target that the scoped run token cannot access, you can provide apifyToken. It is marked isSecret: true, encrypted by Apify, sent only in an Authorization header, and never intentionally written to logs or output.

A downstream full-permission Actor can still require the user's explicit approval in Apify Console.

Sync vs async

Synchronous

Use for short workflows when Retool needs the result immediately. waitTimeoutSeconds supports up to 300 seconds; the bridge handles the Apify API's 60-second per-request wait limit internally.

Asynchronous

Use for long workflows. The bridge starts the target and returns STARTED plus runId immediately. correlationId can store a Retool row/workflow key.

Errors are normalized

Common failures are returned as structured errorType values such as:

• AUTH_ERROR
• INSUFFICIENT_PERMISSIONS
• FULL_PERMISSION_ACTOR_NOT_APPROVED
• NOT_FOUND
• RATE_LIMITED
• NETWORK_ERROR
• INVALID_RESPONSE

The bridge does not charge its custom workflow event if the downstream run was never created.

Pricing

The source defines one PPE event: workflow-execution, charged exactly once after Apify successfully creates the downstream run. Internal retries are never billed twice. Final Store pricing is set in Apify Console.

Task examples

Run an Apify Actor from a Retool button

Use a Retool REST query to start this bridge and pass the current form/table values in targetInput.

Fill a Retool table with Apify dataset results

Use mode: sync, includeDatasetItems: true, and bind OUTPUT.datasetItems to your Retool table.

Start a long Apify workflow from Retool and correlate it later

Use mode: async and set correlationId to your Retool row or job identifier. The returned runId is suitable for later polling/webhook flows.

Limitations

• This Actor does not create a native Retool plugin; it provides a standardized API workflow that Retool can call.
• Dataset retrieval uses the target Actor's default dataset only.
• In async mode dataset items are not retrieved because the target is still running.
• Private tasks or targets outside the scoped run token may require the optional encrypted token.
• The bridge does not bypass Apify permission approvals or downstream Actor pricing.

API / MCP friendly

Inputs are bounded and outputs use deterministic field names, making the Actor suitable for Retool REST queries, API clients, automation platforms, and AI agents that need a simple "run -> wait -> retrieve -> normalize" operation.