Schedule Your First Agent Task in 5 Minutes

Build a scheduled agent task that fires a webhook every hour, with retries and execution logging.

Your agent needs to run on a schedule. Maybe it summarizes emails every morning. Maybe it checks inventory every hour. Maybe it scrapes prices at midnight.

You could use cron. But cron doesn't tell you when a job fails. Cron doesn't retry. Cron doesn't log outcomes. You find out something broke three days later when a customer complains.

CueAPI is a scheduling API for agents. It fires webhooks on time, retries on failure, and logs every execution. This tutorial walks through scheduling a task from zero in under five minutes.

Prerequisites

• Python 3.9 or higher
• A free CueAPI account (10 cues, 300 executions/month)
• An API key from the CueAPI dashboard

Step 1: Install the CueAPI SDK

Install the Python SDK from PyPI.

pip install cueapi

You should see:

Successfully installed cueapi-0.4.2

The SDK wraps the CueAPI REST API so you don't have to manage HTTP requests manually.

Step 2: Set Your API Key

Export the API key as an environment variable. Grab it from the dashboard settings page.

export CUEAPI_API_KEY="cue_sk_your_key_here"

Or pass it directly in code. Environment variables are cleaner for production, but inline works for testing.

from cueapi import CueAPI

client = CueAPI(api_key="cue_sk_your_key_here")

You should see no errors. If the key is invalid, the client raises cueapi.AuthenticationError on the first API call.

Step 3: Create a Cue

A cue is a scheduled task. It has a name, a cron schedule, and a webhook URL that CueAPI calls on each execution.

Create a cue that fires every hour:

from cueapi import CueAPI

client = CueAPI()  # reads CUEAPI_API_KEY from env

cue = client.cues.create(
    name="hourly-inventory-check",
    schedule="0 * * * *",
    webhook_url="https://myapp.example.com/hooks/inventory",
    metadata={"agent": "inventory-bot", "version": "1.0"}
)

print(f"Cue created: {cue.id}")
print(f"Next run: {cue.next_execution_at}")

You should see:

Cue created: cue_a1b2c3d4e5
Next run: 2026-03-14T16:00:00Z

That's it. CueAPI will POST to https://myapp.example.com/hooks/inventory at the top of every hour.

Under the hood, this hits POST /v1/cues with your schedule and webhook configuration.

What CueAPI sends to your webhook

Each execution sends a JSON payload:

{
  "execution_id": "exec_f6g7h8i9j0",
  "cue_id": "cue_a1b2c3d4e5",
  "cue_name": "hourly-inventory-check",
  "scheduled_at": "2026-03-14T16:00:00Z",
  "fired_at": "2026-03-14T16:00:01.234Z",
  "attempt": 1,
  "metadata": {
    "agent": "inventory-bot",
    "version": "1.0"
  }
}

Your handler receives this as a standard POST request. Process it, then respond with a 200 status.

Step 4: Build a Simple Webhook Handler

Here's a minimal Flask handler that receives the webhook and processes the task:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/hooks/inventory", methods=["POST"])
def handle_inventory_check():
    payload = request.get_json()
    execution_id = payload["execution_id"]
    
    print(f"Running inventory check for execution {execution_id}")
    
    # Your agent logic here
    items_checked = 142
    items_low_stock = 3
    
    # Return 200 to confirm delivery
    return jsonify({
        "status": "success",
        "items_checked": items_checked,
        "items_low_stock": items_low_stock
    }), 200

if __name__ == "__main__":
    app.run(port=8080)

Run it:

pip install flask
python handler.py

You should see:

 * Running on http://127.0.0.1:8080

CueAPI considers any 2xx response a successful delivery. A 4xx or 5xx triggers a retry. No response within 30 seconds triggers a timeout retry.

Step 5: Report the Outcome

Delivery and outcome are separate concepts in CueAPI. Delivery means the webhook reached your handler. Outcome means the handler finished its job successfully.

After your agent finishes processing, report the outcome:

import requests
import os

def report_outcome(execution_id, status, details):
    """Report execution outcome to CueAPI."""
    response = requests.post(
        f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome",
        headers={"Authorization": f"Bearer {os.environ['CUEAPI_API_KEY']}"},
        json={
            "status": status,  # "success", "failure", or "partial"
            "details": details
        }
    )
    return response.json()

# In your webhook handler, after processing:
result = report_outcome(
    execution_id="exec_f6g7h8i9j0",
    status="success",
    details={"items_checked": 142, "items_low_stock": 3}
)
print(result)

You should see:

{
  "execution_id": "exec_f6g7h8i9j0",
  "outcome_status": "success",
  "recorded_at": "2026-03-14T16:00:04.567Z"
}

This hits POST /v1/executions/{id}/outcome. Now the CueAPI dashboard shows not just that the webhook fired, but whether the actual task succeeded.

Step 6: Verify Everything Works

List your cues to confirm the setup:

from cueapi import CueAPI

client = CueAPI()

cues = client.cues.list()
for cue in cues:
    print(f"{cue.name} | {cue.schedule} | Next: {cue.next_execution_at} | Status: {cue.status}")

You should see:

hourly-inventory-check | 0 * * * * | Next: 2026-03-14T17:00:00Z | Status: active

Check the CueAPI dashboard for a visual view of executions, delivery statuses, and reported outcomes.

You can also query executions directly via the API:

curl -s -H "Authorization: Bearer $CUEAPI_API_KEY" \
  https://api.cueapi.ai/v1/cues/cue_a1b2c3d4e5/executions | python -m json.tool

You should see:

{
  "executions": [
    {
      "id": "exec_f6g7h8i9j0",
      "status": "delivered",
      "outcome": "success",
      "scheduled_at": "2026-03-14T16:00:00Z",
      "delivered_at": "2026-03-14T16:00:01.234Z",
      "attempts": 1
    }
  ]
}

What Happens When Things Fail

CueAPI retries failed deliveries automatically. If your handler returns a 5xx or times out, CueAPI retries up to 3 times with exponential backoff:

1. First retry: 30 seconds after failure
2. Second retry: 2 minutes after first retry
3. Third retry: 8 minutes after second retry

After 3 failed attempts, the execution is marked as failed and visible in the dashboard. No silent failures. No guessing.

Read the full retry logic guide for configuration options.

Next Steps

• Add webhook signature verification to secure your handler
• Schedule CrewAI agent tasks with CueAPI
• Explore the API reference for advanced cue options like timezone, pause, and one-time schedules

Get started: pip install cueapi