Create and manage reports

Reports are the execution results of your workplans. Each time you run a workplan, it generates a new report with fresh analysis based on current data. This guide explains how to create, monitor, and retrieve reports from your workplans.

Running a workplan to generate a report

Once your workplan is ready, status == "READY", you can execute it to generate a new report.

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 run_workplan(workplan_id):
    """Execute a workplan to generate a new report."""
    url = f"{BASE_URL}/v2/workplans/{workplan_id}/run-workplan"
    
    response = requests.post(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        report_id = data.get("report_id")
        status = data.get("status")
        print(f"Workplan execution started! Report ID: {report_id}")
        print(f"Current status: {status}")
        return report_id
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# Run a workplan to generate a new report
workplan_id = "your-workplan-id"
report_id = run_workplan(workplan_id)

Monitoring report generation

After starting a workplan execution, you can monitor the report’s progress.

import time
def get_report_status(report_id):
    """Check the status of a report generation."""
    url = f"{BASE_URL}/v2/reports/{report_id}/results"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        status = data.get("status")
        created_at = data.get("created_at")
        print(f"Report {report_id}: {status} (created: {created_at})")
        return status
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# Poll until the report is complete
report_status = ""
while report_status not in ["COMPLETE", "ERROR", "CANCELLED"]:
    report_status = get_report_status(report_id)
    
    if report_status in ["ERROR", "CANCELLED", "NO_RESULTS_FOUND"]:
        print(f"Report execution encountered an issue: {status}")
        break
    if report_status != "COMPLETE":
        print("Report still processing... status: {report_status}")
        time.sleep(10)

Report status values

Reports can be in the following states during generation:

NOT_STARTED: The report generation hasn’t begun yet
STARTING: The workplan execution is being initialized
RUNNING: The workplan is actively processing and generating results
COMPLETE: The report has been successfully generated
ERROR: An error occurred during report generation
CANCELLED: The report generation was stopped before completion
NO_RESULTS_FOUND: The workplan completed but couldn’t find relevant results
TOKEN_LIMIT: The workplan hit the token usage limit

Retrieving report output

Once a report is complete, you can retrieve the analysis results.

def get_report_results(report_id):
    """Get the complete results of a generated report."""
    url = f"{BASE_URL}/v2/reports/{report_id}/results"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# Get the complete report results
report_results = get_report_results(report_id)

Report outputs can be of different types:

text: Plain text analysis and explanations
table: Structured data in tabular format
graph: Visual representation of data as a line, bar, or pie chart

Example: Processing different output types

Reports can contain multiple types of outputs. Here’s how to handle each type:

# Get the complete report results
report_results = get_report_results(report_id)
if report_results and "outputs" in report_results:
    for i, item in enumerate(report_results["outputs"]):
        output_data = item["output"]
        output_type = output_data["output_type"]
        
        print(f"\n--- Output {i+1} ({output_type}) ---")
        
        if output_type == "text":
            # Save the text analysis to a file
            with open(f"analysis_{i+1}.txt", "w") as f:
                f.write(output_data["val"])
            print(f"Text analysis saved to analysis_{i+1}.txt")
            
        elif output_type == "table":
            # Export the table to CSV
            import csv
            
            columns = [col["name"] for col in output_data["columns"]]
            with open(f"table_{i+1}.csv", "w", newline="") as f:
                writer = csv.writer(f)
                writer.writerow(columns)
                writer.writerows(output_data["rows"])
            print(f"Table data exported to table_{i+1}.csv")
            
        elif output_type == "graph":
            # Just print info about the graph (in a real app, you might render it)
            graph_type = output_data["graph"]["graph_type"]
            title = output_data["title"]
            print(f"Graph: {title} ({graph_type})")

Cancelling report generation

If you need to stop a report that’s currently being generated, there is an endpoint for that. Note that

def cancel_report(report_id):
    """Cancel a report that is currently being generated."""
    url = f"{BASE_URL}/v2/reports/{report_id}/cancel"
    
    response = requests.post(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        success = data.get("success", False)
        if success:
            print(f"Report {report_id} cancelled successfully")
        return success
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return False
# Cancel a report if needed
cancel_report(report_id)

Listing all your reports

Get an overview of all reports across all your workplans:

def list_all_reports():
    """List all reports across all workplans."""
    url = f"{BASE_URL}/v2/reports"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        reports = data.get("reports", [])
        
        print(f"Total reports: {len(reports)}")
        
        for report in reports:
            print(f"\nReport {report["report_id"]}:")
            print(f"  Workplan: {report["workplan_id"]}")
            print(f"  Status: {report["status"]}")
            print(f"  Created: {report["created_at"]}")
        
        return reports
    else:
        print(f"Error: {response.status_code}, {response.text}")
        return None
# List all reports
all_reports = list_all_reports()

Example: Complete workplan execution

Here’s a complete example of creating and running a workplan to generate a report:

Create a workplan

First, create a workplan for your analysis:

# Create a workplan for market analysis
workplan_prompt = "Analyze Apple's stock performance over the last month and show key metrics in a table"
workplan_id = create_workplan(workplan_prompt)
print(f"Created workplan: {workplan_id}")

Wait for workplan to be ready

Monitor the workplan status until it’s ready:

# Wait for workplan to be ready
while True:
    plan_status, run_status = get_workplan_status(workplan_id)
    if plan_status == "READY":
        print("Workplan is ready to execute!")
        break
    elif plan_status == "FAILED":
        print("Workplan creation failed")
        exit(1)
    time.sleep(10)

Execute the workplan

Run the workplan to generate a report:

# Execute the workplan
report_id = run_workplan(workplan_id)
print(f"Started report generation: {report_id}")

Monitor report progress

Wait for the report to complete:

# Monitor report generation
while True:
    status = get_report_status(report_id)
    if status == "COMPLETE":
        print("Report generation completed!")
        break
    elif status in ["ERROR", "CANCELLED"]:
        print(f"Report failed with status: {status}")
        exit(1)
    time.sleep(10)

Retrieve results

Get the final report results:

# Get the report results
results = get_report_results(report_id)
process_report_outputs(results)

Next steps

Now that you understand how to create and manage reports, you can:

Learn how to schedule and automate workplans to run on a custom schedule
Learn how to monitor token usage efficiently build reports
Explore using documents with your workplans

Each report execution consumes tokens and generates fresh analysis based on current data. Consider your token budget when running workplans frequently.