CueAPI Getting Started Tutorial: Schedule Your First Agent Task

This CueAPI getting started tutorial walks you through scheduling your first AI agent task with delivery confirmation and outcome tracking. You'll set up a cue, receive the webhook, and report back success with proof. In 10 minutes, you'll have an agent that runs on schedule and proves it worked. That's the difference between hoping your agent ran and knowing it did.

TL;DR: Schedule your first agent task with CueAPI. Create a cue via REST API, handle webhook delivery, report outcome with evidence. Your agent becomes accountable for its work, not just scheduled to run.

Key Takeaways: - CueAPI delivers webhooks with 99.97% reliability and 3 retry attempts - Agents report outcomes within 5 minutes to close the accountability gap - One API call schedules your agent across any platform (OpenClaw, Replit, local) - Evidence tracking stores proof your business action actually happened - 15+ execution states track everything from delivery to verified success

What is CueAPI?

CueAPI is a scheduling API that makes AI agents accountable for their work. Unlike platform schedulers that fire and forget, CueAPI confirms delivery and tracks whether your agent actually did what you asked. You schedule a cue. Your agent receives the webhook. Your agent reports outcome with evidence. Now you know your agent worked, not just that it was supposed to.

Prerequisites

You need a machine that can receive HTTP requests for testing. This tutorial uses ngrok to expose a local development server. Your agent can run anywhere, but you need an endpoint CueAPI can reach during setup.

⚠️ Warning: Never put real API keys in webhook URLs or query parameters. Use headers for authentication.

Step 1: Get Your API Key

Sign up at the CueAPI Dashboard and grab your API key. It starts with cue_sk_ and has 64 characters. Store it in your environment as CUEAPI_API_KEY. You get 1,000 executions free every month.

export CUEAPI_API_KEY=cue_sk_your_64_character_api_key_here

Test your key works:

curl -H "Authorization: Bearer $CUEAPI_API_KEY" \
  https://api.cueapi.ai/v1/cues

import httpx

api_key = "cue_sk_your_api_key_here"
headers = {"Authorization": f"Bearer {api_key}"}

response = httpx.get("https://api.cueapi.ai/v1/cues", headers=headers)
print(response.status_code)  # Should be 200
print(response.json())

✅ Expected output: Status 200 with an empty array {"cues": [], "total": 0} if you haven't created any cues yet.

Step 2: Create Your First Cue

A cue is a scheduled agent task with delivery confirmation and outcome tracking. Create one that runs every 5 minutes for testing. Replace YOUR_NGROK_URL with your actual webhook endpoint.

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer $CUEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "morning-briefing",
    "description": "Daily AI agent task for testing",
    "schedule": {
      "type": "recurring", 
      "cron": "*/5 * * * *",
      "timezone": "America/New_York"
    },
    "transport": "webhook",
    "callback": {
      "url": "https://YOUR_NGROK_URL.ngrok.io/webhook",
      "method": "POST",
      "headers": {"X-Agent-Secret": "test123"}
    },
    "payload": {"task": "check_pipeline", "priority": "high"},
    "retry": {
      "max_attempts": 3,
      "backoff_minutes": [1, 5, 15]
    },
    "delivery": {
      "timeout_seconds": 30,
      "outcome_deadline_seconds": 300
    }
  }'

import httpx
import json

api_key = "cue_sk_your_api_key_here"
headers = {"Authorization": f"Bearer {api_key}"}

cue_data = {
    "name": "morning-briefing",
    "description": "Daily AI agent task for testing", 
    "schedule": {
        "type": "recurring",
        "cron": "*/5 * * * *",
        "timezone": "America/New_York"
    },
    "transport": "webhook",
    "callback": {
        "url": "https://YOUR_NGROK_URL.ngrok.io/webhook",
        "method": "POST",
        "headers": {"X-Agent-Secret": "test123"}
    },
    "payload": {"task": "check_pipeline", "priority": "high"},
    "retry": {
        "max_attempts": 3,
        "backoff_minutes": [1, 5, 15]
    },
    "delivery": {
        "timeout_seconds": 30,
        "outcome_deadline_seconds": 300
    }
}

response = httpx.post(
    "https://api.cueapi.ai/v1/cues",
    headers=headers,
    json=cue_data
)

cue = response.json()
print(f"Created cue: {cue['id']}")

✅ Expected output: Status 201 with your cue details including an ID like cue_abc123def456.

📝 Note: The cron /5 runs every 5 minutes for testing. Change to 0 9 for daily 9 AM execution in production.

Step 3: Set Up Your Agent Endpoint

Your agent needs an HTTP endpoint to receive webhooks from CueAPI. Here's a minimal Flask server that confirms receipt and prepares to report outcome:

from flask import Flask, request, jsonify
import httpx
import time

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_cue():
    # Verify the secret header
    secret = request.headers.get('X-Agent-Secret')
    if secret != 'test123':
        return jsonify({'error': 'Invalid secret'}), 401
    
    # Extract execution details
    webhook_data = request.json
    execution_id = webhook_data['execution_id']
    cue_name = webhook_data['cue']['name']
    payload = webhook_data['payload']
    
    print(f"Received cue: {cue_name}")
    print(f"Execution ID: {execution_id}")
    print(f"Payload: {payload}")
    
    # TODO: Do your actual agent work here
    # For now, just simulate work
    time.sleep(2)
    
    # Report successful outcome back to CueAPI
    report_outcome(execution_id, True, "Pipeline checked successfully")
    
    return jsonify({'received': True}), 200

def report_outcome(execution_id, success, result):
    api_key = "cue_sk_your_api_key_here"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    outcome_data = {
        "success": success,
        "result": result,
        "metadata": {"duration_ms": 2000}
    }
    
    response = httpx.post(
        f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome",
        headers=headers,
        json=outcome_data
    )
    
    if response.status_code == 200:
        print("Outcome reported successfully")
    else:
        print(f"Failed to report outcome: {response.status_code}")

if __name__ == '__main__':
    app.run(port=8000, debug=True)

Start your server and expose it with ngrok:

python webhook_server.py

# Terminal 2  
ngrok http 8000

Copy the ngrok URL (like https://abc123.ngrok.io) and update your cue's webhook URL.

⚠️ Warning: ngrok URLs change every restart unless you have a paid account. Update your cue's callback URL if the ngrok URL changes.

Step 4: Test Delivery and Confirm Receipt

Your cue runs every 5 minutes. Watch your webhook server logs to confirm delivery. CueAPI sends a POST request with this structure:

{
  "execution_id": "exec_abc123def456",
  "cue": {
    "id": "cue_abc123def456", 
    "name": "morning-briefing"
  },
  "payload": {"task": "check_pipeline", "priority": "high"},
  "scheduled_at": "2026-03-24T14:05:00Z",
  "attempt": 1
}

Your agent must respond with status 200 within 30 seconds to confirm delivery. CueAPI marks the execution as delivered when your endpoint responds successfully.

✅ Expected output: Your Flask server prints the cue name, execution ID, and payload every 5 minutes.

Step 5: Report Outcome Back to CueAPI

After your agent does its work, report the outcome back to CueAPI. This closes the accountability gap. Silent failures are expensive bugs that cost you users. Outcome tracking prevents them.

curl -X POST https://api.cueapi.ai/v1/executions/exec_abc123def456/outcome \
  -H "Authorization: Bearer $CUEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success": true,
    "result": "Processed 142 records from pipeline",
    "metadata": {"duration_ms": 2450, "records_processed": 142},
    "external_id": "batch:20260324-142"
  }'

import httpx

def report_detailed_outcome(execution_id):
    api_key = "cue_sk_your_api_key_here"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    outcome_data = {
        "success": True,
        "result": "Processed 142 records from pipeline",
        "metadata": {"duration_ms": 2450, "records_processed": 142},
        "external_id": "batch:20260324-142"
    }
    
    response = httpx.post(
        f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome",
        headers=headers,
        json=outcome_data
    )
    
    return response.json()

For verified success, append evidence that proves your business action happened:

def append_evidence(execution_id, tweet_id):
    api_key = "cue_sk_your_api_key_here"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    evidence_data = {
        "external_id": f"tweet:{tweet_id}",
        "result_url": f"https://twitter.com/status/{tweet_id}",
        "result_type": "tweet",
        "summary": "Morning briefing posted to Twitter"
    }
    
    response = httpx.patch(
        f"https://api.cueapi.ai/v1/executions/{execution_id}/evidence",
        headers=headers,
        json=evidence_data
    )
    
    return response.json()

📝 Note: Evidence tracking stores proof your business action actually happened. The tweet ID, email batch ID, or Stripe charge ID. This transforms reported success into verified success.

Step 6: View Execution History

Check your execution history in the CueAPI Dashboard or via API. You'll see delivery confirmations, outcome reports, and evidence for each execution.

curl -H "Authorization: Bearer $CUEAPI_API_KEY" \
  https://api.cueapi.ai/v1/executions?cue_id=cue_abc123def456

import httpx

def get_execution_history(cue_id):
    api_key = "cue_sk_your_api_key_here"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    response = httpx.get(
        f"https://api.cueapi.ai/v1/executions?cue_id={cue_id}",
        headers=headers
    )
    
    executions = response.json()
    for execution in executions['executions']:
        print(f"Status: {execution['status']}")
        print(f"Delivered: {execution['delivered_at']}")
        print(f"Outcome: {execution.get('outcome', 'No outcome yet')}")
    
    return executions

✅ Expected output: A list of executions with status completed, delivery timestamps, and outcome data including your custom metadata.

Beyond the Basics

Now you have a working cue with delivery confirmation and outcome tracking. Here's what to explore next:

Production scheduling: Change your cron to realistic intervals. Use 0 9 * for daily 9 AM runs. Set timezone to match your business hours. See the complete guide to scheduling tasks for AI agents for advanced patterns.

Webhook security: Implement signature verification and rate limiting. Store secrets in environment variables, never in URLs. Follow webhook security best practices to protect your endpoints.

Error handling: Your agent will fail sometimes. Report failures with error details. Use the retry configuration to handle transient issues. CueAPI's 3 retry attempts with exponential backoff handle most temporary problems.

Multiple environments: Create separate cues for development, staging, and production. Use different webhook URLs and API keys. Never test with production data or endpoints.

📝 Note: This tutorial used webhook transport. CueAPI also supports worker transport where your agent polls for tasks. Useful for agents behind firewalls or on dynamic IPs.

Understanding why cron has no concept of success explains why CueAPI exists. Platform schedulers fire and forget. CueAPI makes your agents accountable for results, not just running on time.

Your agent now runs on schedule, confirms delivery, and proves it worked. That's the difference between hoping your agent ran and knowing it did. Make your agents accountable.

Try it yourself. Free tier available: Get started with CueAPI

Frequently Asked Questions

How long does CueAPI wait for my agent to respond?

CueAPI waits 30 seconds for delivery confirmation by default. Configure timeout_seconds in the delivery settings. Your agent has 5 minutes (300 seconds) to report outcome by default, configurable via outcome_deadline_seconds.

What happens if my webhook endpoint is down?

CueAPI retries 3 times with exponential backoff (1, 5, 15 minutes by default). After all retries fail, the execution is marked as failed_to_deliver. Configure retry behavior in the cue's retry settings.

Can I schedule one-time tasks instead of recurring?

Yes. Set schedule.type to once and use schedule.at with an ISO timestamp instead of schedule.cron. Example: {"type": "once", "at": "2026-03-25T14:30:00Z", "timezone": "UTC"}.

How do I pause or delete a cue?

Use PATCH /v1/cues/{id} with {"paused": true} to pause. Use DELETE /v1/cues/{id} to delete permanently. Paused cues stop scheduling new executions but preserve history.

What's the difference between delivery and outcome?

Delivery means your agent received the webhook and responded with status 200. Outcome means your agent completed the work and reported success or failure. Most schedulers only track delivery. CueAPI tracks both to close the accountability gap.

Related Articles

• Scheduled Task Monitoring Python: Track Agent Success with CueAPI

• Why Traditional Cron Is Broken for Modern Applications

Sources

• CueAPI Dashboard: Web interface for managing cues and viewing execution history: https://dashboard.cueapi.ai
• CueAPI API Reference: Complete REST API documentation with all endpoints: https://docs.cueapi.ai/api-reference/overview/
• httpx: Modern Python HTTP client used in code examples: https://www.python-httpx.org/
• ngrok: Tool for exposing local servers to the internet for testing webhooks: https://ngrok.com/

About the author: Govind Kavaturi is co-founder of Vector, a portfolio of AI-native products. He believes the next phase of the internet is built for agents, not humans.