CueAPI Quickstart: Schedule Your First Agent in 5 Minutes

Building AI agents that run reliably is the easy part. Knowing they actually did their work is harder. Most developers schedule their agents with platform cron or custom timers, then hope everything works. This CueAPI quickstart guide shows you how to close that accountability gap in under 10 minutes.

You'll create a cue that delivers a task to your agent, confirms delivery, and tracks whether the work actually happened. No more silent failures. No more finding out from users that your agent went quiet.

TL;DR: Set up CueAPI to schedule your first agent task with delivery confirmation and outcome tracking. Takes 5 minutes. Works on any platform where your agent runs.

Key Takeaways: - CueAPI delivers webhook payloads with 99.97% reliability and 3 automatic retries - Execution visibility means you know your agent received the task AND completed it successfully - Works on OpenClaw, Replit, local machines, cloud servers with no public URL required - Free tier includes 300 executions per month with full accountability features - Takes under 5 minutes to implement basic scheduling with outcome verification

What You'll Build

A scheduled agent task that runs every hour and reports back what it accomplished. Your agent will receive a webhook from CueAPI, do some work, then confirm success with evidence. You'll know within minutes if something goes wrong, not days later when a user complains.

This is different from cron. Cron fires a command and forgets. CueAPI delivers a payload, waits for confirmation, tracks the outcome, and alerts you if anything fails silently.

Prerequisites

You need Python 3.7+ and an agent that can receive HTTP requests. Your agent can run anywhere: OpenClaw, Replit Agent, local machine, cloud server. CueAPI works with all of them.

ℹ️ Your agent doesn't need a public URL. CueAPI can reach agents running on localhost, private networks, and development environments.

Step 1: Get Your API Key

Sign up at CueAPI Dashboard and grab your API key from the settings page. It starts with cue_sk_ and gives you access to 300 free executions per month.

📝 Note: Keep your API key secure. It controls access to your scheduled tasks and execution data.

Step 2: Install HTTP Client

Install httpx or requests for making HTTP calls to the CueAPI REST API:

pip install httpx

Or use requests if you prefer:

pip install requests

CueAPI provides a REST API - there's no Python SDK. You'll use standard HTTP clients to interact with the API.

✅ Success: You can verify the installation by running python -c "import httpx; print('HTTP client ready')"

Step 3: Create Your First Cue

A cue is a scheduled task with accountability built in. Create one that runs every hour and delivers a webhook to your agent:

import httpx

headers = {
    "Authorization": "Bearer cue_sk_your_api_key_here",
    "Content-Type": "application/json"
}

cue_data = {
    "name": "hourly-data-sync",
    "description": "Sync user data from external API",
    "schedule": {
        "type": "recurring",
        "cron": "0 * * * *",  # Every hour
        "timezone": "America/New_York"
    },
    "transport": "webhook",
    "callback": {
        "url": "https://your-agent.com/sync",
        "method": "POST",
        "headers": {"Authorization": "Bearer your-agent-token"}
    },
    "payload": {
        "task": "user_data_sync",
        "source": "external_api",
        "batch_size": 100
    },
    "retry": {
        "max_attempts": 3,
        "backoff_minutes": [1, 5, 15]
    }
}

with httpx.Client() as client:
    response = client.post("https://api.cueapi.ai/v1/cues", json=cue_data, headers=headers)
    cue = response.json()
    print(f"Cue created: {cue['id']}")

Or with curl:

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hourly-data-sync",
    "schedule": {
      "type": "recurring",
      "cron": "0 * * * *",
      "timezone": "America/New_York"
    },
    "transport": "webhook",
    "callback": {
      "url": "https://your-agent.com/sync",
      "method": "POST"
    },
    "payload": {
      "task": "user_data_sync",
      "batch_size": 100
    },
    "retry": {
      "max_attempts": 3,
      "backoff_minutes": [1, 5, 15]
    }
  }'

⚠️ Warning: Replace https://your-agent.com/sync with your actual agent URL. For local development, use your ngrok tunnel or similar.

Expected Output:

{
  "id": "cue_abc123",
  "name": "hourly-data-sync",
  "status": "active",
  "next_run": "2024-03-24T15:00:00Z"
}

Step 4: Handle the Webhook

Your agent needs an endpoint to receive webhooks from CueAPI. Here's a basic Flask handler:

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

app = Flask(__name__)

@app.route('/sync', methods=['POST'])
def handle_sync():
    # Get the execution details from CueAPI
    execution_id = request.headers.get('X-CueAPI-Execution-ID')
    payload = request.json
    
    if not execution_id:
        return jsonify({"error": "Missing execution ID"}), 400
    
    try:
        # Do your agent's work here
        batch_size = payload.get('batch_size', 100)
        
        # Simulate syncing user data
        synced_records = sync_user_data(batch_size)
        
        # Report success to CueAPI
        report_outcome(execution_id, True, f"Synced {synced_records} records")
        
        return jsonify({
            "status": "success",
            "records_synced": synced_records
        })
        
    except Exception as e:
        # Report failure to CueAPI
        report_outcome(execution_id, False, str(e))
        return jsonify({"error": str(e)}), 500

def sync_user_data(batch_size):
    # Your actual sync logic here
    time.sleep(2)  # Simulate work
    return 142  # Return number of records synced

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

📝 Note: CueAPI sends the execution ID in the X-CueAPI-Execution-ID header. You need this to report the outcome back.

Step 5: Report Success Back to CueAPI

This is where accountability happens. Your agent tells CueAPI what it actually accomplished:

def report_outcome(execution_id, success, result):
    url = f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome"
    headers = {
        "Authorization": "Bearer cue_sk_your_api_key_here",
        "Content-Type": "application/json"
    }
    
    data = {
        "success": success,
        "result": result,
        "metadata": {
            "duration_ms": 2000,
            "timestamp": int(time.time())
        }
    }
    
    with httpx.Client() as client:
        response = client.post(url, json=data, headers=headers)
        print(f"Outcome reported: {response.status_code}")

Or with requests:

import requests

def report_outcome(execution_id, success, result):
    url = f"https://api.cueapi.ai/v1/executions/{execution_id}/outcome"
    headers = {
        "Authorization": "Bearer cue_sk_your_api_key_here",
        "Content-Type": "application/json"
    }
    
    data = {
        "success": success,
        "result": result,
        "metadata": {
            "duration_ms": 2000,
            "timestamp": int(time.time())
        }
    }
    
    response = requests.post(url, json=data, headers=headers)
    print(f"Outcome reported: {response.status_code}")

Expected Output:

{
  "execution_id": "exec_xyz789",
  "outcome_recorded_at": "2024-03-24T14:32:15Z",
  "status": "completed_success"
}

✅ Success: When you see completed_success, CueAPI knows your agent received the task AND finished it successfully.

Step 6: Test Your Setup

Test your cue by polling for claimable executions:

import httpx
import time

headers = {
    "Authorization": "Bearer cue_sk_your_api_key_here",
    "Content-Type": "application/json"
}

with httpx.Client() as client:
    response = client.get("https://api.cueapi.ai/v1/executions/claimable", headers=headers)
    executions = response.json()
    
    if executions:
        execution_id = executions[0]['id']
        print(f"Found execution: {execution_id}")
        
        # Claim the execution
        claim_response = client.post(f"https://api.cueapi.ai/v1/executions/{execution_id}/claim", headers=headers)
        print(f"Claimed execution: {claim_response.status_code}")

Expected flow:

1. CueAPI delivers webhook to your agent
2. Your agent processes the task
3. Your agent reports outcome to CueAPI
4. CueAPI updates execution status to completed_success

⚠️ Warning: If your agent doesn't report an outcome within 5 minutes, CueAPI marks the execution as completed_unknown.

What Happens Next

Your cue runs every hour. CueAPI delivers the webhook, waits for your agent to confirm success, and tracks everything. You can see execution history, success rates, and failure details in the CueAPI dashboard.

This is execution visibility in action. You know your agent ran. You know it finished. You know what it accomplished. No more silent failures.

Troubleshooting Common Issues

Webhook not received: Check your agent's URL and firewall settings. CueAPI retries failed deliveries 3 times with exponential backoff.

Outcome not recorded: Make sure you're sending the execution ID from the webhook headers back to CueAPI when reporting outcomes.

Executions marked as unknown: Your agent isn't reporting outcomes within the deadline. Check your error handling and network timeouts.

Cue not triggering: Verify your cron expression and timezone. Use crontab.guru to test cron syntax.

📝 Note: Check the full API reference for advanced configuration options.

Next Steps

Now that you have basic scheduling with accountability, explore these advanced features:

• Add evidence to executions with external IDs and result URLs
• Set up email and webhook alerts for failures
• Configure different retry strategies for different types of work
• Use verification modes to automatically validate outcomes

Read our complete guide to agent scheduling to learn about production deployment patterns. Or see why your agent's cron job failed for more context on the accountability problem.

Want to migrate from cron to CueAPI? Our migration guide covers common patterns and gotchas.

Understand how silent failures cost you users and why accountability matters for production agents.

Try it yourself. Free tier available. Get your API key and make your agents accountable. Know they worked. Get on with building.

Frequently Asked Questions

Can I use CueAPI without a Python SDK?

Yes. CueAPI is a REST API that works with any HTTP client in any language. There is no Python SDK - you use standard HTTP libraries like httpx, requests, or aiohttp.

What happens if my agent is temporarily down?

CueAPI retries webhook delivery 3 times with exponential backoff (1, 5, 15 minutes). If all retries fail, the execution is marked as failed and you get an alert.

Do I need a public URL for my agent?

No. CueAPI can reach agents on localhost, private networks, and VPNs. Use ngrok for local development or deploy wherever your agent runs.

How is this different from cron?

Cron fires a command and forgets. CueAPI delivers a payload, confirms receipt, tracks outcomes, and alerts on failures. You get accountability, not just scheduling.

What's the difference between delivery and outcome?

Delivery means your agent received the webhook. Outcome means your agent finished the work and reported results. CueAPI tracks both separately.

Related Articles

• Schedule AI Agent Task CueAPI: Step by Step Tutorial

• Cron Job Monitoring Is Not Enough: Why AI Agents Need More

Sources

• CueAPI API Reference: Complete REST API documentation: https://docs.cueapi.ai/api-reference/overview/
• CueAPI Dashboard: Web interface for managing cues and viewing executions: https://dashboard.cueapi.ai
• Flask Documentation: Python web framework for building webhooks: https://flask.palletsprojects.com/
• Crontab Guru: Cron expression validator and generator: https://crontab.guru/

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.