---
title: "Start a run, or schedule a repeating one"
method: POST
path: "/api/v1/agents/{id}/runs"
tags: ["Agents API"]
---

# Start a run, or schedule a repeating one

`POST /api/v1/agents/{id}/runs`

## Request

- Base URL: `https://three.ws`
- URL: `https://three.ws/api/v1/agents/{id}/runs`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `goal` string, required: What the run should accomplish.
  - `maxSteps` integer
  - `budgetCreditsUsd` number
  - `budgetUsd` number: On-chain budget. Needs wallet:write.
  - `model` string: Model id.
  - `temperature` number
  - `toolsAllowed` string[]
  - `scheduledFor` string, date-time: ISO 8601 start time.
  - `schedule` string: Cron expression. Creates an automation that starts a run on that schedule.

## Response `200`

The { data, meta: { requestId, timestamp } } envelope.

## Other responses

- `201`: Created. Same envelope.
- `400`: invalid_parameter, bad_json or a route-specific validation code.
- `401`: unauthorized
- `403`: insufficient_scope
- `404`: not_found
- `429`: rate_limited, with Retry-After.

---

[API](https://skmtc.dev/three/apis/three-ws-api.md) · [All operations](https://skmtc.dev/three/apis/three-ws-api/llms.txt) · [OpenAPI document](https://skmtc.dev/three/apis/three-ws-api/revisions/dbc5e3a81b79?raw)