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.

# 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
  }'

# 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):

{
  "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.

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

Response (200):

{
  "schedules": [ /* AgentScheduleResponse objects */ ],
  "total": 1
}

GET /{schedule_id}

Get a single schedule's details.

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}).

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.

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.

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

Response (200):

{
  "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
}