Schedule and automate workplans

Once you’ve created workplans to analyze your data, you’ll often want them to update automatically to reflect the latest information. This guide explains how to schedule and automate your workplans to keep their outputs fresh.

Create a schedule

You can customize when your workplan runs using natural language schedules. If the system is unable to parse the request, the workplan will be scheduled to run daily at 8AM in the US/Eastern timezone. You can make further edits this schedule using the same endpoint.

1 def set_workplan_schedule(workplan_id, schedule_description, timezone=None):
2     """Set a custom schedule for a workplan using natural language."""
3     url = f"{BASE_URL}/v2/workplans/{workplan_id}/set-schedule"
4     payload = {
5         "user_schedule_description": schedule_description
6     }
7     
8     if timezone:
9         payload["workplan_timezone"] = timezone
10     
11     response = requests.post(url, headers=headers, json=payload)
12     
13     if response.status_code == 200:
14         data = response.json()
15         print(f"Schedule updated: {data['schedule']['generated_schedule_description']}")
16         print(f"Next run will use timezone: {data['schedule']['timezone']}")
17         return data
18     else:
19         print(f"Error: {response.status_code}, {response.text}")
20         return None
21 
22 # Set a custom schedule
23 set_workplan_schedule("your-workplan-id", "Weekly on Friday at 3pm", "US/Pacific")

The schedule is interpreted by our backend and converted to the appropriate cron expression. You can use natural language to describe when you want your workplan to run.

Example schedule descriptions

Here are some examples of schedule descriptions you can use:

“Daily at 9:30am”: Every day at 9:30 AM
“Weekly on Monday at 7am”: Every Monday at 7:00 AM
“Every weekday at 4pm”: Monday through Friday at 4:00 PM
“Monthly on the 1st at 12pm”: First day of each month at 12:00 PM

Example: Schedule an earnings report workplan to run weekly

Identify the workplan

Select the earnings report workplan you want to schedule

Set the schedule

Configure it to run weekly before market open:

1 # Schedule weekly earnings report before market open
2 workplan_id = "earnings-report-123456"
3 schedule = "Weekly on Monday at 8:30am"
4 timezone = "US/Eastern"
5 
6 result = set_workplan_schedule(workplan_id, schedule, timezone)
7 print(f"Your earnings report will run every Monday at 8:30am Eastern Time")

View workplan schedule

You can view a workplan’s schedule using the view-schedule endpoint. If no schedule is associated with a workplan, schedule will be null.

1 def view_workplan_schedule(workplan_id):
2     """View a workplan's schedule."""
3     url = f"{BASE_URL}/v2/workplans/{workplan_id}/view-schedule"
4     
5     response = requests.get(url, headers=headers)
6 
7     if response.status_code == 200:
8         data = response.json()
9     else:
10         print(f"Error: {repsonse.status_code}, {response.text}")
11         return False
12 
13 # View workplan schedule
14 view_workplan_schedule(workplan_id)

Cancel workplan schedule

If you to cancel workplan scheduling, you can delete the schedule using the delete-schedule endpoint:

1 def delete_workplan_schedule(workplan_id):
2     """Deletes a workplan's schedule."""
3     url = f"{BASE_URL}/v2/workplans/{workplan_id}/delete-schedule"
4     payload = {}
5     
6     response = requests.post(url, headers=headers, json=payload)
7     
8     if response.status_code == 200:
9         data = response.json()
10         if data.get("success"):
11             print("Automation successfully disabled")
12         return data.get("success", False)
13     else:
14         print(f"Error: {response.status_code}, {response.text}")
15         return False
16 
17 # Delete workplan schedule
18 delete_workplan_schedule("your-workplan-id")

Manually triggering updates

If you need updated results immediately, you can manually run a workplan.

1 def rerun_workplan(workplan_id):
2     """Manually trigger a workplan to run again."""
3     url = f"{BASE_URL}/v2/workplans/{workplan_id}/run-workplan"
4     payload = {}
5     
6     response = requests.post(url, headers=headers, json=payload)
7     
8     if response.status_code == 200:
9         data = response.json()
10         success = data.get("success", False)
11         if success:
12             print("Workplan rerun successfully initiated")
13         return success
14     else:
15         print(f"Error: {response.status_code}, {response.text}")
16         return False
17 
18 # Rerun our workplan to get fresh data
19 rerun_workplan("your-workplan-id")

After triggering a rerun, you’ll need to check the workplan’s status again and retrieve the new outputs once it completes.

Example: Rerun after breaking news

Breaking news happens

A significant event occurs that impacts your analysis

Trigger immediate update

Don’t wait for the next scheduled run:

1 # Trigger immediate update after breaking news
2 workplan_id = "breaking-news-analyzer-123"
3 
4 # Trigger the rerun
5 rerun_success = rerun_workplan(workplan_id)
6 
7 if rerun_success:
8     print("Breaking news analysis has been initiated!")