HomeTool CallingSchedule tool execution

Schedule tool execution

Sometimes you need tools to run at a specific time in the future rather than immediately. Arcade supports scheduling tool execution through its API, allowing you to set up tasks to run at predetermined times.

This guide will walk you through scheduling tool calls using the Arcade API.

When to use scheduled execution

Scheduled tool execution is useful for:

  • Time-sensitive operations: Execute tools at optimal times (e.g., send emails during business hours)
  • Delayed actions: Set up follow-up tasks or reminders
  • Batch processing: Run resource-intensive operations during off-peak hours

How scheduling works

When you execute a tool with Arcade, you can provide a run_at parameter that specifies when the tool should run. The Arcade Engine will store your request and execute it at the specified time.

The run_at parameter accepts timestamps in ISO 8601 format: YYYY-MM-DDTHH:MM:SS

Set up your Arcade client

First, make sure you have the Arcade client installed and configured with your API key.

pip install arcadepy

Schedule a tool execution

Here’s how to schedule a tool to run at a future time:

import arcadepy
from datetime import datetime, timedelta
 
# Initialize the client
client = arcadepy.Client(api_key="YOUR_API_KEY")
 
# Calculate a time 1 hour from now
future_time = datetime.now() + timedelta(hours=1)
# Format as ISO 8601
run_at = future_time.strftime("%Y-%m-%dT%H:%M:%S")
 
# Schedule the tool execution
response = client.tools.execute(
    tool_name="Slack.SendMessage",
    input={
        "channel_name": "general",
        "message": "This is a scheduled message from Arcade!"
    },
    run_at=run_at  # The tool will run at this time
)
 
print(f"Tool scheduled! Execution ID: {response.execution_id}")
print(f"Will run at: {response.run_at}")

Check scheduled execution status

After scheduling a tool, you can check its status using the execution ID:

# Get details about a scheduled execution
execution_details = client.tools.scheduled.get(
    id=response.execution_id
)
 
print(f"Status: {execution_details.execution_status}")
print(f"Scheduled for: {execution_details.run_at}")
print(f"Tool: {execution_details.tool_name}")

List scheduled executions

You can also retrieve a list of all your scheduled tool executions:

# List all scheduled executions
scheduled_tools = client.tools.scheduled.list(
    limit=10,
    offset=0
)
 
for execution in scheduled_tools.items:
    print(f"Tool: {execution.tool_name}")
    print(f"Scheduled for: {execution.run_at}")
    print(f"Status: {execution.execution_status}")
    print("---")

Practical examples

Schedule a daily report

Schedule a Google Sheets report to run every morning at 9 AM:

from datetime import datetime, time, timedelta
 
# Get tomorrow at 9 AM
tomorrow = datetime.now().date() + timedelta(days=1)
run_time = datetime.combine(tomorrow, time(9, 0, 0))
 
response = client.tools.execute(
    tool_name="GoogleSheets.UpdateSpreadsheet",
    input={
        "spreadsheet_id": "your-spreadsheet-id",
        "range": "A1:D10",
        "values": [["Daily Report", datetime.now().strftime("%Y-%m-%d")]]
    },
    run_at=run_time.strftime("%Y-%m-%dT%H:%M:%S")
)

Schedule a follow-up email

Send a follow-up email 3 days after an initial contact:

# Schedule for 3 days from now
follow_up_time = datetime.now() + timedelta(days=3)
 
response = client.tools.execute(
    tool_name="Gmail.SendEmail",
    input={
        "to": "contact@example.com",
        "subject": "Following up on our conversation",
        "body": "Hi! I wanted to follow up on our discussion from earlier this week..."
    },
    run_at=follow_up_time.strftime("%Y-%m-%dT%H:%M:%S")
)

Important considerations

⚠️
Time zones: The run_at parameter expects times in UTC. Make sure to convert your local time to UTC when scheduling.
Execution precision: Scheduled tools typically execute within a few seconds of the specified time, but exact timing depends on system load.
💡
Authorization: Ensure that any required authorizations for the tool will still be valid at the scheduled execution time.

Response handling

When you schedule a tool execution, the response includes:

  • execution_id: Unique identifier for tracking the scheduled execution
  • execution_type: Will be "scheduled" for scheduled executions
  • run_at: The time when the tool is scheduled to run
  • status: Initial status (typically "scheduled")
  • success: Boolean indicating if the scheduling was successful
{
  "execution_id": "exec_abc123",
  "execution_type": "scheduled",
  "run_at": "2024-01-15T09:00:00",
  "status": "scheduled",
  "success": true,
  "tool_name": "Slack.SendMessage"
}

Next steps