> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# Create your first workplan

Alfa workplans are reusable analysis plans that define what analysis to perform. This guide explains how to create, monitor, and manage workplans. Once created, workplans can be executed multiple times to generate reports with fresh data.

## Understanding Workplans vs Reports

* **Workplan**: An execution plan based on the user's prompts to create reports.
* **Report**: A single execution of a workplan that generates a report.

A workplan can generate multiple reports. See the [schedule and automate workplans](/guides/build-with-alfa/scheduling-workplans/schedule-and-automate-workplans) guide for more details.

## Creating your first workplan

Creating a workplan is simple - you just need to provide a clear prompt that describes what you want the workplan to do.

```python
import requests

BASE_URL = "https://alfa.boosted.ai/client"
API_KEY = "YOUR_API_KEY_HERE"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

def create_workplan(prompt, args=None):
    """Create a new workplan with the specified prompt."""
    url = f"{BASE_URL}/v2/workplans/create"
    payload = {"prompt": prompt}
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code == 200:
        data = response.json()
        workplan_id = data.get("workplan_id")
        status = data.get("status")
        print(f"Success! Workplan created with ID: {workplan_id}")
        print(f"Status: {status}")
        return workplan_id
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None

# Create a workplan to analyze Microsoft's stock performance
workplan_id = create_workplan("What was MSFT's close price on Feb 1, 2023 and how does it compare to recent performance?")
```

> **Tip**
>
> For complex analyses, you can include placeholders like `{doc}` in your prompt to reference custom documents. See our [Custom Documents](/guides/using-alfa/knowledge-base/custom-documents#creating-workplans-with-custom-documents) guide for details.

### Example: Creating a workplan for comprehensive price target analysis

#### Define your analysis needs

Determine what specific market data you want to analyze

#### Formulate your prompt

Create a clear prompt that specifies exactly what you need:

```python
comprehensive_prompt = """
Show a line graph of Target Price Consensus Mean over the past year for Apple. Then show current
Target Price Consensus High and Target Price Consensus Low in a table. Finally, in a new section,
get all news developments for the target company, then get the articles associated with those developments.
Pass the articles to the text to table tool and extract all the analysts that have given ratings and their
price targets, using the columns research firm, price target, date, and buy/sell recommendation.
"""
```

#### Create the workplan

```python
# Create price target analysis workplan
analysis_workplan_id = create_workplan(comprehensive_prompt)

print(f"Your price target analysis workplan is being created with ID: {analysis_workplan_id}")
```

## Monitoring workplan creation

After creating a workplan, it goes through a processing phase to build the execution plan. You can check its status to know when it's ready.

```python
import time

def get_workplan_status(workplan_id):
    """Check if a workplan has completed its creation and is ready."""
    url = f"{BASE_URL}/v2/workplans/{workplan_id}/view"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        plan_status = data.get("plan_status")
        run_status = data.get("run_status")
        print(f"Plan status: {plan_status}, Run status: {run_status}")
        return plan_status, run_status
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None, None

# Poll until the workplan is ready
plan_status = ""
while plan_status != "READY":
    plan_status, run_status = get_workplan_status(workplan_id)
    if plan_status == "READY":
        print("Workplan is ready!")
        break
    elif plan_status == "FAILED":
        print("Workplan creation failed")
        break
    else:
        print("Workplan is still being created...")
        time.sleep(10)
```

The workplan can be in one of the following states during creation:

* `CREATING`: The workplan is being created and processed
* `READY`: The workplan is ready to be executed
* `FAILED`: The workplan creation failed
* `CANCELLED`: The workplan creation was cancelled

Once a workplan has its status set as `READY`, you can view the execution plan created from the user prompt.

```python
def get_workplan_details(workplan_id):
    """Get detailed information about a workplan."""
    url = f"{BASE_URL}/v2/workplans/{workplan_id}/view"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        
        print(f"Workplan ID: {data.get('workplan_id')}")
        print(f"Plan Status: {data.get('plan_status')}")
        print(f"Run Status: {data.get('run_status')}")
        
        execution_plan = data.get("execution_plan")
        if execution_plan:
            nodes = execution_plan.get("nodes", [])
            print(f"Execution Plan: {len(nodes)} nodes")
            
            for i, node in enumerate(nodes):
                tool_name = node.get("tool_name", "Unknown")
                description = node.get("description", "No description")
                print(f"  Node {i+1}: {tool_name} - {description}")
        
        return data
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None

# Get details for a specific workplan
workplan_info = get_workplan_details(workplan_id)
```

## Next steps

Now that you know how to create and manage workplans, you can:

* Learn how to [edit and manage workplans](/guides/build-with-alfa/workplans/edit-and-manage-workplans) to modify and improve existing workplans
* Learn how to [create and manage reports](/guides/build-with-alfa/workplans/create-and-manage-reports) to build reports with Alfa
* Learn how to [schedule and automate workplans](/guides/build-with-alfa/scheduling-workplans/schedule-and-automate-workplans) to run on a custom schedule
* Explore using [documents](/guides/build-with-alfa/knowledge-base/documents) with your workplans

> **Tip**
>
> For production systems, always implement proper error handling and consider using exponential backoff for status polling to avoid rate limiting.