---
title: "Create a scheduled task for one of the user's agents"
method: POST
path: "/api/mcp/tools/schedule_agent_task"
tags: ["tools"]
---

# Create a scheduled task for one of the user's agents

`POST /api/mcp/tools/schedule_agent_task`

## Request

- Base URL: `https://finestructure.ai`
- URL: `https://finestructure.ai/api/mcp/tools/schedule_agent_task`
- Auth: HTTP bearer

Create a scheduled task for one of the user's agents. Supported schedule types: once (run_at ISO local time + timezone), interval (interval_minutes 5-1440), hourly, daily (time HH:MM + timezone), weekly (time + timezone + days_of_week 0=Sunday..6), cron (5-field expression + timezone), manual (only runs on demand). Returns the normalized schedule and the computed next_run_at so you can read the fire time back to the user in their timezone.

## Request body

- object
  - `agent_id` string, required: The agent id (from create_agent or list_agents)
  - `title` string, required: Short task title
  - `instructions` string, required: What the agent should do on each run, written as instructions to the agent
  - `schedule` object, required: Schedule object, e.g. {"type":"daily","time":"08:30","timezone":"Asia/Jerusalem"} or {"type":"weekly","time":"09:00","timezone":"Asia/Jerusalem","days_of_week":[0]} or {"type":"once","run_at":"2026-08-20T09:00","timezone":"Asia/Jerusalem"}
  - `max_runs` integer: Optional cap on total runs (0 = unlimited)
  - `activate` boolean: Start the schedule immediately (true) or save as draft (false)

## Response `200`

Tool executed successfully

- ToolResult
  - `ok` boolean, required
  - `tool` string, required
  - `result` object, required

## Other responses

- `400`: Invalid arguments for this tool
- `401`: Missing or invalid bearer token
- `402`: Not enough credits on the account
- `403`: Token scope does not permit this tool
- `404`: Unknown tool name
- `429`: Rate limit exceeded, retry after the indicated delay
- `500`: Internal error while executing the tool

---

[API](https://skmtc.dev/finestructure/apis/fine-structure-api.md) · [All operations](https://skmtc.dev/finestructure/apis/fine-structure-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finestructure/apis/fine-structure-api/revisions/02c50ed5fd70?raw)