TL;DR CueAPI lets you schedule agent tasks with webhook delivery, automatic retries, and verified success reporting in under 5 minutes. Create a cue with a cron schedule, build a webhook handler to process the task, and report outcomes back to track real success. No more silent failures or wondering if your agents actually worked.
Key Takeaways • Free tier includes 10 cues and 300 executions per month to get started • Failed webhooks retry automatically up to 3 times with 1, 5, and 15 minute backoff intervals • Webhook timeout limit is 30 seconds before triggering a retry attempt • CueAPI tracks both delivery status (webhook reached your handler) and outcome status (task actually succeeded)
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.
But there's an accountability gap. How do you know your agent actually worked? Traditional scheduling tools fire tasks but don't verify success. You find out something broke three days later when a customer complains.
CueAPI is a scheduling API for AI agents. It fires webhooks on time, retries on failure, and logs every execution with verified success reporting. 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: Set Up Your HTTP Client
Install httpx for making API requests:
pip install httpxYou should see:
Successfully installed httpx-0.25.0We'll use httpx to interact with the CueAPI REST API directly.
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.
import httpx
import os
api_key = os.environ.get("CUEAPI_API_KEY", "cue_sk_your_key_here")
headers = {"Authorization": f"Bearer {api_key}"}You should see no errors. If the key is invalid, the API returns a 401 status on the first request.
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:
curl:
curl -X POST https://api.cueapi.ai/v1/cues \
-H "Authorization: Bearer $CUEAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "hourly-inventory-check",
"description": "Check inventory levels every hour",
"schedule": {
"type": "recurring",
"cron": "0 * * * *",
"timezone": "UTC"
},
"transport": "webhook",
"callback": {
"url": "https://myapp.example.com/hooks/inventory",
"method": "POST"
},
"payload": {
"agent": "inventory-bot",
"version": "1.0"
},
"retry": {
"max_attempts": 3,
"backoff_minutes": [1, 5, 15]
}
}'Python:
import httpx
import os
response = httpx.post(
"https://api.cueapi.ai/v1/cues",
headers={"Authorization": f"Bearer {os.environ['CUEAPI_API_KEY']}"},
json={
"name": "hourly-inventory-check",
"description": "Check inventory levels every hour",
"schedule": {
"type": "recurring",
"cron": "0 * * * *",
"timezone": "UTC"
},
"transport": "webhook",
"callback": {
"url": "https://myapp.example.com/hooks/inventory",
"method": "POST"
},
"payload": {
"agent": "inventory-bot",
"version": "1.0"
},
"retry": {
"max_attempts": 3,
"backoff_minutes": [1, 5, 15]
}
}
)
cue = response.json()
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:00ZThat's it. CueAPI will POST to https://myapp.example.com/hooks/inventory at the top of every hour. This scheduling API runs anywhere and tracks every execution.
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,
"payload": {
"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({
"message": "Inventory check completed",
"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.pyYou should see:
* Running on http://127.0.0.1:8080CueAPI 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 for verified success:
curl:
curl -X POST https://api.cueapi.ai/v1/executions/exec_f6g7h8i9j0/outcome \
-H "Authorization: Bearer $CUEAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"success": true,
"result": "Checked 142 items, 3 low stock",
"metadata": {
"items_checked": 142,
"items_low_stock": 3
}
}'Python:
import httpx
import os
def report_outcome(execution_id, success, result, metadata=None):
"""Report execution outcome to CueAPI."""
response = httpx.post(
f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome",
headers={"Authorization": f"Bearer {os.environ['CUEAPI_API_KEY']}"},
json={
"success": success,
"result": result,
"metadata": metadata or {}
}
)
return response.json()
# In your webhook handler, after processing:
result = report_outcome(
execution_id="exec_f6g7h8i9j0",
success=True,
result="Checked 142 items, 3 low stock",
metadata={"items_checked": 142, "items_low_stock": 3}
)
print(result)You should see:
{
"execution_id": "exec_f6g7h8i9j0",
"success": true,
"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:
curl:
curl -H "Authorization: Bearer $CUEAPI_API_KEY" \
https://api.cueapi.ai/v1/cuesPython:
import httpx
import os
response = httpx.get(
"https://api.cueapi.ai/v1/cues",
headers={"Authorization": f"Bearer {os.environ['CUEAPI_API_KEY']}"}
)
cues = response.json()["cues"]
for cue in cues:
print(f"{cue['name']} | {cue['schedule']['cron']} | Next: {cue['next_execution_at']} | Status: {cue['status']}")You should see:
hourly-inventory-check | 0 * * * * | Next: 2026-03-14T17:00:00Z | Status: activeCheck 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.toolYou 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:
- First retry: 1 minute after failure
- Second retry: 5 minutes after first retry
- Third retry: 15 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
FAQ
How many cues can I create on the free plan? The free tier allows 10 cues with up to 300 executions per month. This covers most development and testing needs before upgrading to a paid plan.
What happens if my webhook endpoint is down? CueAPI retries failed webhooks up to 3 times with exponential backoff (1, 5, and 15 minutes). If all attempts fail, the execution is marked as failed in the dashboard.
Can I change the cron schedule after creating a cue? Yes, you can update the schedule using the PUT /v1/cues/{id} endpoint. Changes take effect immediately and the next execution time is recalculated.
How do I pause a cue temporarily? Set the cue status to paused using the API or dashboard. Paused cues skip scheduled executions but retain their configuration. Set status back to active to resume.
What timezone should I use for scheduling? You can specify any IANA timezone in the schedule configuration (like America/New_York or Europe/London). UTC is used by default if no timezone is specified.
Do I need to report outcomes for every execution? No, outcome reporting is optional but recommended. Without it, you only know if the webhook was delivered, not if your agent task actually succeeded.
Related Articles
- What Is CueAPI? - The scheduling API for AI agents
- Cron vs API Scheduling - Side by side comparison
- OpenClaw Agent Setup - CueAPI on OpenClaw step by step
Frequently Asked Questions
How many agent tasks can I schedule with the free tier?
The free tier includes 10 cues and 300 executions per month to get you started. This gives you plenty of room to test CueAPI and build your first scheduled agent workflows before upgrading to a paid plan.
What happens if my webhook endpoint fails to respond?
CueAPI automatically retries failed webhooks up to 3 times with intelligent backoff intervals of 1, 5, and 15 minutes. This ensures temporary network issues or service hiccups don't cause your agent tasks to be permanently lost.
How long does my webhook handler have to process the agent task?
Your webhook endpoint has 30 seconds to respond before CueAPI considers it a timeout and triggers a retry attempt. Make sure your agent processing logic can complete within this window or implement asynchronous processing patterns.
What's the difference between delivery status and outcome status in CueAPI?
Delivery status tracks whether the webhook successfully reached your handler endpoint, while outcome status tracks whether your agent task actually succeeded. CueAPI monitors both so you can distinguish between network failures and agent logic failures.
Can I schedule agent tasks to run at different timezones?
Yes, CueAPI supports timezone-aware scheduling using standard cron expressions. You can specify any valid timezone when creating your cue, ensuring your agent tasks fire at the correct local time regardless of where your servers are located.
Sources
- CueAPI REST API Reference - Complete API documentation with endpoints and examples
- CueAPI Webhook Signatures Guide - Security implementation for webhook verification
- CueAPI Retry Logic Documentation - Detailed explanation of failure handling and retry configuration
- CueAPI Getting Started Guide - Account setup and basic concepts overview
- CueAPI Dashboard - Visual interface for managing cues and monitoring executions
Make your agents accountable. Free to start.
Get started with the CueAPI REST API. Make your agents accountable. Know they worked. Get on with building.
About the Author
Govind Kavaturi is co-founder of Vector Apps Inc. and CueAPI. Previously co-founded Thena (reached $1M ARR in 12 months, backed by Lightspeed, First Round, and Pear VC, with customers including Cloudflare and Etsy). Building AI-native products with small teams and AI agents. Forbes Technology Council member.
