# Workflow Orchestrator (`the.beast/workflow-orchestrator`) Actor

Chain 11,000+ Apify Actors into automated workflows. Pre-built templates for price comparison, lead generation, SEO analysis. 5x faster with parallel execution, auto-retry on failures. Perfect for AI agents.

- **URL**: https://apify.com/the.beast/workflow-orchestrator.md
- **Developed by:** [mr beast](https://apify.com/the.beast) (community)
- **Categories:** AI, MCP servers, Automation
- **Stats:** 15 total users, 1 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## AI Workflow Automation

**Just describe what you want. AI figures out the rest.**

No more learning 11,000+ Actors. No more writing JSON workflows. Just tell it what you need in plain English.

```
"Find 20 AI startups in Austin and get their contact emails"
```

AI automatically:

1. Breaks down your request into steps
2. Selects the best Actors for each task
3. Executes the workflow
4. Summarizes results in clean, AI-ready format

### 3 Ways to Use

#### 1. AI Mode (Recommended)

Just describe what you want:

```json
{
    "prompt": "Compare laptop prices on Amazon and eBay",
    "openaiApiKey": "sk-or-...",
    "maxBudget": 5.00
}
```

> **Note:** Uses OpenRouter API (get free key at [openrouter.ai](https://openrouter.ai)). Supports GPT-4, Claude, Llama, and more.

AI will:

- Decompose into tasks (search Amazon, search eBay)
- Select appropriate Actors
- Execute in parallel
- Return summarized comparison

#### 2. Template Mode

Use pre-built workflows:

```json
{
    "template": "lead-generation-pipeline"
}
```

**Available Templates:**

- `ecommerce-price-comparison` - Amazon + eBay price tracking
- `lead-generation-pipeline` - Google → Scrape → Extract emails
- `real-estate-market-analysis` - Zillow listings
- `social-media-monitoring` - Track brand mentions
- `seo-competitor-analysis` - SERP + page analysis
- `news-aggregation` - Multi-source news
- `review-sentiment-analysis` - Google Maps reviews

#### 3. Custom Workflow

Define your own:

```json
{
    "workflow": {
        "name": "my-workflow",
        "steps": [
            {
                "id": "search",
                "actorId": "apify/google-search-scraper",
                "input": { "queries": ["AI companies Austin"] }
            },
            {
                "id": "scrape",
                "actorId": "apify/cheerio-scraper",
                "dependsOn": ["search"],
                "inputMappings": [{
                    "sourceStepId": "search",
                    "sourceField": "organicResults",
                    "targetField": "startUrls"
                }]
            }
        ]
    }
}
```

### Key Features

| Feature | Description |
|---------|-------------|
| **AI Task Decomposition** | Natural language → executable workflow |
| **Smart Actor Selection** | AI picks the best Actor for each task |
| **Cost Estimation** | Know the cost before running |
| **Parallel Execution** | Run 10 steps simultaneously |
| **Auto-Retry** | Failed steps retry automatically |
| **LLM-Optimized Output** | Clean summaries for AI agents |
| **Dry Run Mode** | Preview without executing |

### Input Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `prompt` | string | Describe what you want in plain English |
| `openaiApiKey` | string | OpenRouter API key (free at openrouter.ai) |
| `template` | string | Pre-built workflow template ID |
| `workflow` | object | Custom workflow definition |
| `maxBudget` | number | Maximum spend limit ($) |
| `outputFormat` | string | `llm-optimized`, `markdown`, `json`, `raw` |
| `maxConcurrency` | integer | Parallel steps (1-10) |
| `dryRun` | boolean | Preview only, don't execute |

### Output Formats

#### LLM-Optimized (Default)

Compact, token-efficient summary perfect for AI agents:

```markdown
### Summary
Found 20 AI companies in Austin with contact information.

### Key Findings
- 18/20 companies have public email addresses
- Most common domain: .io (40%)
- Average company size: 15-50 employees

### Top Contacts
- TechCo AI: hello@techco.ai
- DataFlow: contact@dataflow.io
...
```

#### JSON

Structured data for programmatic use.

#### Markdown

Human-readable report format.

#### Raw

Unprocessed scraper output.

### Pricing

| Event | Price |
|-------|-------|
| AI Decomposition | $0.005 |
| Workflow Step | $0.001 |
| Workflow Completed | $0.002 |

**Example:** AI-powered 3-step workflow ≈ $0.01

### Use Cases

**Sales Teams**

> "Find SaaS companies in San Francisco, get decision-maker emails"

**E-commerce**

> "Track competitor prices on Amazon, eBay, Walmart daily"

**Real Estate**

> "Monitor Zillow for new listings under $500K in Austin"

**Marketing**

> "Aggregate news about AI from 10 sources, summarize key trends"

**Research**

> "Collect Google Maps reviews for coffee shops, analyze sentiment"

### AI Agent Integration

Works with Claude, Cursor, LangChain, and any MCP client.

#### Claude Desktop

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": ["-y", "@apify/actors-mcp-server"],
            "env": {
                "APIFY_TOKEN": "your_token"
            }
        }
    }
}
```

Then just ask Claude:

> "Use the AI workflow automation Actor to find and contact AI startups"

### Examples

#### Lead Generation

```json
{
    "prompt": "Find 50 marketing agencies in New York, scrape their websites, extract contact emails and phone numbers",
    "openaiApiKey": "sk-...",
    "outputFormat": "json"
}
```

#### Price Monitoring

```json
{
    "prompt": "Compare prices for 'Sony WH-1000XM5' on Amazon vs eBay",
    "openaiApiKey": "sk-...",
    "maxBudget": 2.00
}
```

#### Competitive Intelligence

```json
{
    "prompt": "Analyze top 10 Google results for 'project management software', extract their features and pricing",
    "openaiApiKey": "sk-..."
}
```

#### Dry Run (Preview)

```json
{
    "prompt": "Find tech jobs in Austin",
    "openaiApiKey": "sk-...",
    "dryRun": true
}
```

Returns what WOULD be executed without running.

### How It Works

```
1. You describe what you want
           ↓
2. AI decomposes into tasks
           ↓
3. AI maps tasks to Actors
           ↓
4. Cost estimation & preview
           ↓
5. Parallel execution
           ↓
6. AI summarizes results
           ↓
7. Clean, actionable output
```

### Limitations

- Requires OpenRouter API key for AI features (free at openrouter.ai)
- Max 50 steps per workflow
- Max 10 concurrent steps
- Max 24 hour timeout

### Changelog

#### v3.0.0 (2026-01-12)

- AI Task Decomposition: Natural language prompts
- Smart Actor Selection: AI picks best Actors
- Cost Estimation: Budget control
- LLM-Optimized Output: Token-efficient summaries
- Dry Run Mode: Preview before executing

#### v2.0.0 (2026-01-11)

- Pre-built templates
- Parallel execution
- Auto-retry

#### v1.0.0 (2026-01-10)

- Initial release

# Actor input Schema

## `prompt` (type: `string`):

Describe your task in plain English. AI will figure out which Actors to use and execute automatically. Example: 'Find 20 AI startups in Austin and extract their contact emails'

## `openaiApiKey` (type: `string`):

Your OpenRouter API key for AI-powered features. Get one free at openrouter.ai. Supports GPT-4, Claude, Llama, and more.

## `apifyApiToken` (type: `string`):

REQUIRED to execute workflows. Your Apify API token to call other Actors. Find it at: console.apify.com/account#/integrations

## `template` (type: `string`):

Use a pre-built workflow template instead of AI decomposition.

## `workflow` (type: `object`):

Advanced: Define your own multi-step workflow with specific Actors and configurations.

## `maxBudget` (type: `number`):

Maximum amount to spend on this workflow. AI will optimize to stay within budget.

## `outputFormat` (type: `string`):

How to format the results. 'llm-optimized' is best for AI agents.

## `maxConcurrency` (type: `integer`):

Run up to 10 steps simultaneously. Higher = faster workflows.

## `timeout` (type: `integer`):

Maximum workflow duration. Default: 1 hour.

## `enableRetry` (type: `boolean`):

Automatically retry failed steps up to 3 times.

## `dryRun` (type: `boolean`):

Show what would be executed without actually running. Great for testing prompts.

## Actor input object example

```json
{
  "prompt": "Find 20 AI companies in Austin TX, scrape their websites, and extract contact emails",
  "template": "",
  "workflow": {
    "name": "my-workflow",
    "steps": []
  },
  "maxBudget": 5,
  "outputFormat": "llm-optimized",
  "maxConcurrency": 3,
  "timeout": 3600,
  "enableRetry": true,
  "dryRun": false
}
```

# Actor output Schema

## `workflowResults` (type: `string`):

Dataset containing results from each workflow step

## `workflowState` (type: `string`):

Full workflow state including all step results

## `workflowSummary` (type: `string`):

Summary of workflow execution with duration and success/failure counts

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "prompt": "Find 20 AI companies in Austin TX, scrape their websites, and extract contact emails",
    "workflow": {
        "name": "my-workflow",
        "steps": []
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("the.beast/workflow-orchestrator").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "prompt": "Find 20 AI companies in Austin TX, scrape their websites, and extract contact emails",
    "workflow": {
        "name": "my-workflow",
        "steps": [],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("the.beast/workflow-orchestrator").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "prompt": "Find 20 AI companies in Austin TX, scrape their websites, and extract contact emails",
  "workflow": {
    "name": "my-workflow",
    "steps": []
  }
}' |
apify call the.beast/workflow-orchestrator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,the.beast/workflow-orchestrator"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/2mdd8gEAE1JMNbdVs/builds/eTZdV6c4bAB811foR/openapi.json