---
title: "Start an agent run on a site"
method: POST
path: "/sites/{site_id}/agent_runners"
tags: ["agentRunner"]
---

# Start an agent run on a site

`POST /sites/{site_id}/agent_runners`

## Request

- Base URL: `https://api.netlify.com/api/v1`
- URL: `https://api.netlify.com/api/v1/sites/{site_id}/agent_runners`
- Auth: OAuth 2
  - Implicit: `https://app.netlify.com/authorize`

Starts an agent run on the site.

## Request body

- AgentRunnerSetup
  - `prompt` string, required
  - `branch` string: Branch to start from. Defaults to the site's production branch.
  - `deploy_id` string: Deploy to start from. Takes precedence over `branch`.
  - `agent` string: Agent to run, for example `claude` or `codex`.
  - `model` string: Model for the agent to use. Omit to let Netlify choose.
  - `effort` 'low' | 'medium' | 'high': Reasoning effort. Omit to let the agent decide.
  - `mode` 'normal' | 'ask': `normal` (the default) changes code; `ask` answers questions without changing code.

## Response `200`

OK

- AgentRunner
  - `id` string
  - `site_id` string
  - `parent_agent_runner_id` string
  - `state` string: One of `new`, `running`, `await_input`, `interrupted`, `error`, `done`, `cancelled` or `archived`.
  - `created_at` string, dateTime
  - `updated_at` string, dateTime
  - `done_at` string, dateTime
  - `title` string
  - `branch` string
  - `result_branch` string
  - `pr_url` string
  - `pr_branch` string
  - `pr_state` string: One of `open`, `draft`, `merged` or `closed`.
  - `pr_number` integer
  - `pr_is_being_created` boolean
  - `pr_error` string
  - `current_task` string: What the agent is working on in the active session.
  - `result_diff` string
  - `sha` string
  - `merge_commit_sha` string
  - `merge_commit_error` string
  - `merge_commit_is_being_created` boolean
  - `base_deploy_id` string
  - `attached_file_keys` string[]
  - `active_session_created_at` string, dateTime
  - `has_result_diff` boolean: Whether the run has changes, available from `GET /agent_runners/{agent_runner_id}/diff`.
  - `latest_session_deploy_id` string
  - `latest_session_deploy_url` string
  - `preview_state` string: State of the deploy building the latest preview. Null until that deploy exists; `ready` once the preview is live.
  - `user` AgentRunnerUser
    - `id` string
    - `full_name` string
    - `email` string
    - `avatar_url` string

## Other responses

- `400`: `prompt_required` or `invalid_request`.
- `403`: `plan_not_eligible` or `ai_credit_limit_disabled`.
- `404`: The site or deploy wasn't found (`deploy_not_found`), the deploy's files are no longer available (`deploy_zip_unavailable`), or agent runners aren't enabled for the site.
- `422`: `deploy_zip_unavailable`.
- `429`: `concurrency_limit_reached`, `ai_credit_limit_exceeded` or `ai_credit_limit_reached`.
- `default`: error

## Changes

- **2026-10-19** `4ee761b12c37`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/netlify/apis/netlify-s-api-documentation/changes/sites/:site_id/agent_runners/post.md)

---

[API](https://skmtc.dev/netlify/apis/netlify-s-api-documentation.md) - [All operations](https://skmtc.dev/netlify/apis/netlify-s-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/netlify/apis/netlify-s-api-documentation/revisions/6546d2e27b7a?raw)