Scheduled Agents (Cron)

Run any UAPI agent on a recurring schedule. Cron jobs invoke your agent with a prompt you define — perfect for daily reports, periodic monitoring, lead generation sweeps, content pipelines, or any task you'd otherwise trigger by hand.

Under the hood, each cron job is an AWS EventBridge Scheduler schedule that calls your agent through the standard chat API with your own access token. No servers, no infrastructure — just a schedule and a prompt.

How It Works

1. You create a cron job with a name, target agent, schedule expression, and an input message (the prompt sent to the agent on each run).
2. EventBridge Scheduler triggers the executor at each scheduled time.
3. The executor invokes your agent via POST /agent/{agentId}/chat on the streaming API, authenticated with your user access token (fetched securely at execution time — never stored in the cron record).
4. Results are logged to your request logs like any other agent invocation, and the cron record tracks lastRunAt, lastRunStatus, and lastRunError.

Schedule Formats

Two expression types are supported:

Format	Example	Meaning
Rate	rate(5 minutes)	Every 5 minutes
Rate	rate(1 hour)	Every hour
Rate	rate(1 day)	Every day
Cron	cron(0 9 * * ? *)	Daily at 9:00 AM
Cron	cron(0 9 ? * MON-FRI *)	Weekdays at 9:00 AM
Cron	cron(30 17 ? * FRI *)	Fridays at 5:30 PM

Cron expressions use the EventBridge 6-field format: cron(minute hour day-of-month month day-of-week year).

Timezones

Cron expressions default to UTC. Set scheduleTimezone to an IANA timezone (e.g. America/New_York, Europe/London) to evaluate the schedule in local time — including daylight saving transitions:

{
  "schedule": "cron(0 9 * * ? *)",
  "scheduleTimezone": "America/Denver"
}

Quick Start

Create a daily report agent run with one API call:

curl -X POST https://api.universalapi.co/cron \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-market-report",
    "agentId": "YOUR_AGENT_ID",
    "schedule": "cron(0 7 * * ? *)",
    "scheduleTimezone": "America/New_York",
    "inputMessage": "Generate the daily market report and upload it to my Knowledge storage as a markdown file."
  }'

The agent receives inputMessage as its prompt on every run. Since agents can use MCP tools — Knowledge uploads, web search, sending Slack messages, even chaining to other agents — a single scheduled prompt can drive an entire workflow.

You can also manage cron jobs visually from the Cron page in the UAPI dashboard.

Lifecycle & Status

Each cron job has a status:

Status	Meaning
active	Schedule is enabled and firing
paused	Schedule is disabled (set manually)
error	Auto-paused after 3 consecutive failures

Auto-Pause on Failure

If an agent invocation fails 3 times in a row (consecutiveFailures reaches 3), the cron job is automatically set to error and the underlying schedule is disabled. This protects your credit balance from a misconfigured agent burning credits on a tight schedule.

To recover: fix the underlying issue, then set status back to active via PUT /cron/{cronId} — this resets the failure counter and re-enables the schedule.

Pausing & Resuming

# Pause
curl -X PUT https://api.universalapi.co/cron/CRON_ID \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

# Resume
curl -X PUT https://api.universalapi.co/cron/CRON_ID \
  -H "Authorization: Bearer uapi_ut_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Limits & Billing

• Maximum 20 cron jobs per user.
• Each scheduled run is billed as a normal agent invocation — credits are charged based on token usage and any tool calls the agent makes. There is no extra charge for the scheduling itself.
• Runs appear in your request logs like any other agent chat, so you can audit exactly what each scheduled run did and cost.

Security

• Your access token is never stored in the cron record. At execution time, the executor looks up your active user token from secure token storage and uses it to authenticate the agent invocation.
• Cron jobs can only invoke agents with the permissions your own token carries.

Common Patterns

Daily digest to Slack — agent connected to a Slack-capable MCP server, scheduled weekday mornings:

{
  "name": "morning-digest",
  "agentId": "...",
  "schedule": "cron(0 8 ? * MON-FRI *)",
  "scheduleTimezone": "America/Chicago",
  "inputMessage": "Search for overnight news about our industry and post a 5-bullet summary to the #news Slack channel."
}

Hourly monitoring — agent checks an endpoint or data source and alerts on anomalies:

{
  "name": "site-monitor",
  "agentId": "...",
  "schedule": "rate(1 hour)",
  "inputMessage": "Check https://example.com/status. If anything is degraded, send me an SMS summarizing the issue."
}

Weekly lead generation — agent searches Reddit/Google for leads and appends to a report:

{
  "name": "weekly-lead-finder",
  "agentId": "...",
  "schedule": "cron(0 6 ? * MON *)",
  "scheduleTimezone": "America/Denver",
  "inputMessage": "Find new leads matching our ICP from the past week and update the leads file in my Knowledge storage."
}

Next Steps

• Cron API Reference — full endpoint documentation
• Creating Agents — build the agent your cron job will invoke
• Request Logs — audit scheduled runs