Agents
Cron agents are scheduled Claude tasks that run automatically on a cron schedule. Each agent has a prompt, a schedule, and optional budget/turn limits. Agents execute via the Claude Agent SDK and their runs are logged with cost and token tracking.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/agents | List all agents |
| POST | /api/agents | Create an agent |
| GET | /api/agents/:id | Get a single agent |
| PATCH | /api/agents/:id | Update an agent |
| DELETE | /api/agents/:id | Delete an agent |
| POST | /api/agents/:id/run | Trigger a manual run |
| POST | /api/agents/:id/cancel | Cancel running executions |
| GET | /api/agents/:id/runs | Get run history |
| GET | /api/agents/:id/stats | Get agent-specific stats |
| GET | /api/agents/stats | Get global agent stats |
All endpoints require authentication.
List Agents
GET /api/agents
Return all agents, ordered alphabetically by name. Includes the creator relation.
Response: 200 OK
{
"data": [
{
"id": "agent-1",
"name": "Daily Digest",
"description": "Summarizes open tasks every morning",
"schedule": "0 9 * * *",
"prompt": "Review all open tasks and create a summary...",
"enabled": true,
"maxTurns": 50,
"maxBudgetUsd": 0.50,
"lastRunAt": "2025-01-07T09:00:00.000Z",
"lastStatus": "success",
"creator": { "id": "user-1", "name": "Tony" },
"createdAt": "2025-01-01T00:00:00.000Z"
}
]
}
Create Agent
POST /api/agents
Create a new cron agent. If enabled is true (the default), the agent is immediately scheduled.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Agent name |
| description | string | No | What the agent does |
| schedule | string | Yes | Cron expression (e.g., 0 9 * * *) |
| prompt | string | Yes | Prompt sent to Claude on each run |
| enabled | boolean | No | Whether to schedule immediately. Default: true |
| maxTurns | number | No | Maximum conversation turns per run. Default: 50 |
| maxBudgetUsd | number | No | Maximum cost per run in USD |
Response: 200 OK
{
"data": {
"id": "agent-2",
"name": "Weekly Review",
"schedule": "0 17 * * 5",
"prompt": "Review completed tasks this week...",
"enabled": true,
"maxTurns": 50,
"createdAt": "2025-01-07T10:00:00.000Z"
}
}
Get Agent
GET /api/agents/:id
Return a single agent with its creator relation.
Response: 200 OK
{
"data": {
"id": "agent-1",
"name": "Daily Digest",
"schedule": "0 9 * * *",
"prompt": "Review all open tasks...",
"enabled": true,
"maxTurns": 50,
"maxBudgetUsd": 0.50,
"creator": { "id": "user-1", "name": "Tony" }
}
}
Returns 404 if the agent does not exist.
Update Agent
PATCH /api/agents/:id
Update one or more fields on an agent. If schedule or enabled is changed, the cron job is rescheduled or unscheduled accordingly.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | No | New name |
| description | string | No | New description |
| schedule | string | No | New cron expression |
| prompt | string | No | New prompt |
| enabled | boolean | No | Enable or disable scheduling |
| maxTurns | number | No | New turn limit |
| maxBudgetUsd | number or null | No | New budget or null to remove limit |
Response: 200 OK
{
"data": {
"id": "agent-1",
"name": "Daily Digest",
"enabled": false,
"updatedAt": "2025-01-07T14:00:00.000Z"
}
}
Delete Agent
DELETE /api/agents/:id
Permanently delete an agent and all associated runs. The cron job is unscheduled before deletion.
Agent deletion is a hard delete. All run history for the agent is permanently removed via cascade.
Response: 200 OK
{
"data": {
"id": "agent-1",
"name": "Daily Digest"
}
}
Trigger Manual Run
POST /api/agents/:id/run
Start an agent run immediately, outside of its cron schedule. The run executes asynchronously -- the endpoint returns immediately without waiting for completion.
Response: 200 OK
{
"message": "Agent started"
}
Monitor run progress via the runs endpoint or the dashboard UI.
Cancel Running Executions
POST /api/agents/:id/cancel
Cancel all currently running executions for an agent.
Returns 404 if no running executions are found.
Response: 200 OK
{
"success": true,
"message": "Cancelled 1 running execution(s)",
"cancelledCount": 1
}
Get Run History
GET /api/agents/:id/runs
Return run history for a specific agent, ordered by start time (newest first).
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| limit | number | Maximum number of runs to return. Default: 100 |
| period | string | Time window: 24h, 7d, or 30d |
Response: 200 OK
{
"data": [
{
"id": "run-1",
"agentId": "agent-1",
"status": "success",
"output": "Created summary document...",
"costUsd": 0.032,
"inputTokens": 1500,
"outputTokens": 800,
"numTurns": 5,
"startedAt": "2025-01-07T09:00:00.000Z",
"completedAt": "2025-01-07T09:01:30.000Z",
"durationMs": 90000
}
]
}
Run statuses: running, success, error, budget_exceeded, cancelled.
Get Agent Stats
GET /api/agents/:id/stats
Return aggregated statistics for a single agent over a time period.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| period | string | Time window: 24h, 7d, or 30d. Default: 7d |
Response: 200 OK
{
"data": {
"totalRuns": 14,
"successRate": 93,
"avgDurationMs": 85000,
"totalCostUsd": 0.45,
"lastRunAt": "2025-01-07T09:00:00.000Z",
"dailyRuns": [
{ "date": "2025-01-06", "success": 2, "error": 0, "total": 2, "costUsd": 0.06 },
{ "date": "2025-01-07", "success": 1, "error": 1, "total": 2, "costUsd": 0.07 }
]
}
}
Get Global Stats
GET /api/agents/stats
Return aggregated statistics across all agents.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
| period | string | Time window: 24h, 7d, or 30d. Default: 7d |
Response: 200 OK
{
"data": {
"totalAgents": 3,
"activeAgents": 2,
"runsInPeriod": 28,
"successRate": 89,
"totalCostUsd": 1.24,
"runningAgentIds": ["agent-1"],
"dailyRuns": [
{ "date": "2025-01-06", "success": 4, "error": 1, "total": 5, "costUsd": 0.18 },
{ "date": "2025-01-07", "success": 3, "error": 0, "total": 3, "costUsd": 0.12 }
]
}
}