🆕Scheduled Runs

Scheduled Runs allow you to can schedule any Prompt Studio agent to run at specific intervals.

You can schedule as many schedules as you want per agent. Each agent can have multiple schedules, allowing you to run it at multiple intervals or for each one of your users.

Each Scheduled Run creates an Agent Run, so you can expect them to work similarly. In fact, the difference between Scheduled Runs and Agent Runs is that Agent Runs run once immediately, while Scheduled Runs run at a cadence. Just like Agent Runs, you can optionally specify a bundle to further tailor the functionality of your agent, as well as a Toolhouse ID metadata.

Agent tokens are free

All Scheduled Runs use a premium LLM model. For a limited time, LLM tokens are free, meaning you will not need to worry about cost per token. Your account will only be charged for Toolhouse Execs.

Getting started with Scheduled Runs

The minimum cadence for a Scheduled Run is every 10 minutes. If you specify a shorter cadence, the your agent will run at the minimum cadence.

Make sure you have your API Key ready. You can see or create an API key in the API Keys page.

Specifying a cadence

You'll need to specify how often you want to agent to run. The minimum cadence is every 10 minutes. To specify a cadence, simply provide a cron expression or a plain text description of the cadence. Scheduled Runs has a dedicated endpoint to translate plain text to cron:

Python

import requests
import json

def send_request(toolhouse_api_key, cadence):
    params = { "cron": cadence }
    url = "https://api.toolhouse.ai/v1/text-to-cron"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
    }

    response = requests.get(url, params=params, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    cadence = "sundays at 5pm UTC"

    response = send_request(toolhouse_api_key, cadence)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

JavaScript

async function createAgentRun(toolhouseApiKey, cadence) {
  try {
    const url = new URL('https://api.toolhouse.ai/v1/text-to-cron');
    url.searchParams.set('cron', cadence);
    const headers = {
      'Authorization': `Bearer ${toolhouseApiKey}`,
    };

    const response = await fetch(url, { headers });

    if (response.ok) {
      const data = await response.json();
      console.log(data);
    } else {
      console.error('Failed to retrieve data:', response.status, response.statusText);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Example usage
const toolhouseApiKey = 'YOUR_TOOLHOUSE_API_KEY';
const cadence = 'sundays 5pm UTC';
await createAgentRun(toolhouseApiKey, cadence);

cURL

curl "https://api.toolhouse.ai/v1/text-to-cron?cron=sundays+5pm+UTC" \
-H "Authorization: Bearer $YOUR_TOOLHOUSE_API_KEY"

This will return a cron expression you can use in subsequent requests.

{
  "data": "0 17 * * 0"
}

Creating a Scheduled Run

1. Head over to Prompt Studio and create a chat. If you're looking for inspiration, you can use this prompt.

2. Click the Share button, then copy the Chat ID.

1. Create an Scheduled Run using the Scheduled Runs API:

Python

import requests
import json

def send_request(toolhouse_api_key, chat_id):
    url = "https://api.toolhouse.ai/v1/schedules"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    # Set the JSON payload
    payload = {
        "chat_id": chat_id,
        "cadence": "0 17 * * 0",
    }

    # Send the POST request
    response = requests.post(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    chat_id = "YOUR_CHAT_ID"

    response = send_request(toolhouse_api_key, chat_id)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

JavaScript

async function createAgentRun(toolhouseApiKey, chatId) {
  try {
    const url = 'https://api.toolhouse.ai/v1/agent-runs';
    const headers = {
      'Authorization': `Bearer ${toolhouseApiKey}`,
      'Content-Type': 'application/json',
    };

    const body = JSON.stringify({
      'chat_id': chatId,
      'cadence': '0 17 * * 0',
    });

    const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: body,
    });

    if (response.ok) {
      const data = await response.json();
      console.log(data);
    } else {
      console.error('Failed to retrieve data:', response.status, response.statusText);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Example usage
const toolhouseApiKey = 'YOUR_TOOLHOUSE_API_KEY';
const chatId = 'your_chat_id';
await createAgentRun(toolhouseApiKey, chatId);

cURL

curl "https://api.toolhouse.ai/v1/agent-runs" \
-H "Authorization: Bearer $YOUR_TOOLHOUSE_API_KEY" \
--json '{
  "chat_id": "your_chat_id",
  "cadence": "0 17 * * 0"
}'

Your Scheduled Run entry will be created.

{
  "data": {
    "id": "bcb7e865-9e6c-xxxx-xxxx-c0110fdf5c2e",
    "created_at": "2025-01-15T01:46:23.568338",
    "updated_at": "2025-01-15T01:46:23.568338",
    "cadence": "0 17 * * 0",
    "active": true,
    "bundle": "default",
    "toolhouse_id": "default"
  }
}

Changing the cadence of a Scheduled Run

You can change the cadence of a Scheduled Run at any time.

Python

import requests
import json

def send_request(toolhouse_api_key, schedule_id, cadence):
    url = f"https://api.toolhouse.ai/v1/schedules/{schedule_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "cadence": cadence
    }

    response = requests.put(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    schedule_id = "YOUR_SCHEDULE_ID"
    cadence = "0 */3 * * *"

    response = send_request(toolhouse_api_key, schedule_id, cadence)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

JavaScript

async function updateScheduleCadence(toolhouseApiKey, scheduleId, cadence) {
  try {
    const url = `https://api.toolhouse.ai/v1/schedules/${scheduleId}`;
    const headers = {
      'Authorization': `Bearer ${toolhouseApiKey}`,
      'Content-Type': 'application/json',
    };

    const body = JSON.stringify({
      'cadence': cadence,
    });

    const response = await fetch(url, {
      method: 'PUT',
      headers: headers,
      body: body,
    });

    if (response.ok) {
      const data = await response.json();
      console.log(data);
    } else {
      console.error('Failed to update cadence:', response.status, response.statusText);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Example usage
const toolhouseApiKey = 'YOUR_TOOLHOUSE_API_KEY';
const scheduleId = 'YOUR_SCHEDULE_ID';
const cadence = '0 */3 * * *';

await updateScheduleCadence(toolhouseApiKey, scheduleId, cadence);

cURL

curl -X PUT \
  "https://api.toolhouse.ai/v1/schedules/$YOUR_SCHEDULE_ID" \
  -H 'Authorization: Bearer $YOUR_TOOLHOUSE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"cadence": "0 */3 * * *"}'

Pausing or resuming a Scheduled Run

When you pause a Scheduled Run, you interrupt its scheduled cadence without deleting it by setting its activefield to false. This is useful to keep the configuration of your Scheduled Run without deleting it completely. You can resume its execution at any time by changing its activefield back to true.

Any currently active Runs will pause at the end of their execution.

Python

import requests
import json

def send_request(toolhouse_api_key, schedule_id, is_active):
    url = f"https://api.toolhouse.ai/v1/agent-runs/{schedule_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "active": is_active
    }

    response = requests.put(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    schedule_id = "YOUR_SCHEDULE_ID"
    is_active = False

    response = send_request(toolhouse_api_key, schedule_id, is_active)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

JavaScript

async function updateScheduleStatus(toolhouseApiKey, scheduleId, isActive) {
  try {
    const url = `https://api.toolhouse.ai/v1/agent-runs/${scheduleId}`;
    const headers = {
      'Authorization': `Bearer ${toolhouseApiKey}`,
      'Content-Type': 'application/json',
    };

    const payload = {
      'active': isActive,
    };

    const response = await fetch(url, {
      method: 'PUT',
      headers: headers,
      body: JSON.stringify(payload),
    });

    if (response.ok) {
      const data = await response.json();
      console.log(data);
    } else {
      console.error('Failed to retrieve data:', response.status, response.statusText);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Example usage
const toolhouseApiKey = 'YOUR_TOOLHOUSE_API_KEY';
const scheduleId = 'YOUR_SCHEDULE_ID';
const isActive = false;

updateScheduleStatus(toolhouseApiKey, scheduleId, isActive);

cURL

curl -XPUT \
  "https://api.toolhouse.ai/v1/schedules/$YOUR_SCHEDULE_ID" \
  -H 'Authorization: Bearer $YOUR_TOOLHOUSE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"active": false}'

Deleting a Scheduled Run

Lastly, you can completely delete a Scheduled Run. Any currently active Runs will stop running at the end of their execution.

Python

import requests
import json

def send_request(toolhouse_api_key, schedule_id):
    url = f"https://api.toolhouse.ai/v1/agent-runs/{schedule_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
    }
    
    response = requests.delete(url, headers=headers)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    schedule_id = "YOUR_SCHEDULE_ID"

    response = send_request(toolhouse_api_key, schedule_id)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

JavaScript

async function cancelScheduleRun(toolhouseApiKey, scheduleId) {
  try {
    const url = `https://api.toolhouse.ai/v1/agent-runs/${scheduleId}`;
    const headers = {
      'Authorization': `Bearer ${toolhouseApiKey}`,
    };

    const response = await fetch(url, {
      method: 'DELETE',
      headers: headers,
    });

    if (response.ok) {
      console.log('Request successful. Response:', await response.json());
    } else {
      console.error('Request failed with status code', response.status);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Example usage
const toolhouseApiKey = 'YOUR_TOOLHOUSE_API_KEY';
const scheduleId = 'YOUR_SCHEDULE_ID';
await cancelScheduleRun(toolhouseApiKey, scheduleId);

cURL

curl -XDELETE \
  "https://api.toolhouse.ai/v1/schedules/$YOUR_SCHEDULE_ID" \
  -H 'Authorization: Bearer $YOUR_TOOLHOUSE_API_KEY'