---
title: "Agent Scheduling"
description: "Run agents on a recurring cron or interval schedule with run history"
canonical: "https://docs.ainative.studio/docs/agent-cloud/scheduling"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Agent Scheduling

Source: https://docs.ainative.studio/docs/agent-cloud/scheduling

> Run agents on a recurring cron or interval schedule with run history

# Agent Scheduling

Run a registered agent automatically on a recurring schedule — either a **cron** expression or a fixed **interval**. Schedules are stored server-side and executed by Celery Beat; every run is recorded so you can inspect its history.

**Base path:** `/api/v1/cloud/agents/{agent_id}/schedules`

You must be the agent's owner to create or manage its schedules.

## POST /

Create a cron or interval schedule for an agent.

```bash
# Cron: every day at 09:00 UTC
curl -X POST https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_type": "cron",
    "cron_expression": "0 9 * * *",
    "timezone": "UTC",
    "task_payload": {"job": "daily-report"},
    "enabled": true
  }'
```

```bash
# Interval: every 5 minutes
curl -X POST https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_type": "interval",
    "interval_seconds": 300,
    "enabled": true
  }'
```

**Request fields:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `schedule_type` | string | **yes** | `cron` or `interval`. |
| `cron_expression` | string | required for cron | Standard 5-field cron: `minute hour day month weekday` (e.g. `0 9 * * *`). |
| `interval_seconds` | int | required for interval | Seconds between runs. Min `60`, max `86400`. |
| `timezone` | string | no | IANA timezone. Default `UTC`. |
| `task_payload` | object | no | JSON payload passed to the agent at each run. |
| `enabled` | bool | no | Whether the schedule is active. Default `true`. |

**Response (201):**
```json
{
  "id": "b7e6c1a2-3f4d-5e6f-7a8b-9c0d1e2f3a4b",
  "agent_id": "agent-a1b2c3d4e5f6",
  "schedule_type": "cron",
  "cron_expression": "0 9 * * *",
  "interval_seconds": null,
  "timezone": "UTC",
  "task_payload": {"job": "daily-report"},
  "enabled": true,
  "last_run_at": null,
  "next_run_at": "2026-08-21T09:00:00Z",
  "run_count": 0,
  "created_at": "2026-08-20T12:00:00Z",
  "updated_at": "2026-08-20T12:00:00Z"
}
```

## GET /

List all schedules for an agent.

```bash
curl https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "schedules": [ /* AgentScheduleResponse objects */ ],
  "total": 1
}
```

## GET /\{schedule_id\}

Get a single schedule's details.

```bash
curl https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules/b7e6c1a2-3f4d-5e6f-7a8b-9c0d1e2f3a4b \
  -H "Authorization: Bearer $TOKEN"
```

## PUT /\{schedule_id\}

Update a schedule. All fields are optional — send only what you want to change (e.g. pause a schedule with `{"enabled": false}`).

```bash
curl -X PUT https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules/b7e6c1a2-3f4d-5e6f-7a8b-9c0d1e2f3a4b \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cron_expression": "0 12 * * *",
    "enabled": true
  }'
```

**Request fields (all optional):** `cron_expression`, `interval_seconds` (60–86400), `timezone`, `task_payload`, `enabled`.

## DELETE /\{schedule_id\}

Delete a schedule and its run history. Returns `204 No Content`.

```bash
curl -X DELETE https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules/b7e6c1a2-3f4d-5e6f-7a8b-9c0d1e2f3a4b \
  -H "Authorization: Bearer $TOKEN"
```

## GET /\{schedule_id\}/runs

List the run history for a schedule.

```bash
curl https://api.ainative.studio/api/v1/cloud/agents/agent-a1b2c3d4e5f6/schedules/b7e6c1a2-3f4d-5e6f-7a8b-9c0d1e2f3a4b/runs \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "runs": [
    {
      "id": "run-uuid",
      "schedule_id": "b7e6c1a2-3f4d-5e6f-7a8b-9c0d1e2f3a4b",
      "agent_id": "agent-a1b2c3d4e5f6",
      "status": "completed",
      "started_at": "2026-08-21T09:00:00Z",
      "completed_at": "2026-08-21T09:00:04Z",
      "result": {"ok": true},
      "error_message": null
    }
  ],
  "total": 1
}
```