---
title: "Begin an agent run"
method: POST
path: "/v1/source-connections/{id}/agent-runs"
tags: ["Source Plane"]
---

# Begin an agent run

`POST /v1/source-connections/{id}/agent-runs`

## Request

- Base URL: `https://brain.inite.ai`
- URL: `https://brain.inite.ai/v1/source-connections/{id}/agent-runs`
- Auth: HTTP bearer

Opens one run (a `source_sync` job_run, actor `agent:<id>`) and answers with whether the walk must be full (first run, or requested), the checkpoint to resume from, the content policy and the fetch budget. One running agent run per connection — a second begin is 409. The local agent’s wire (docs/source-plane.md § Agent): the connector runs on the agent’s machine, the engine keeps the books here. Scope brain:write — a tenant write key, never an admin one; it reaches only the connections an operator pointed at its host (`host: agent:<id>`). Source plane operator surface (docs/roadmap/raw-evidence-sources-2026-09.md) — answers a bare 404 until `SOURCE_PLANE_ENABLED=1`.

Required scope: `brain:write`.

## Path parameters

- `id` string, required

## Request body

- BeginAgentRunRequest
  - `agentId` string, required
  - `full` boolean

## Response `201`

The run.

- BeginAgentRunResponse
  - `checkpoint` object, nullable, required
  - `contentPolicy` 'manifest' | 'text' | 'bytes', required
  - `fetchBudget` integer, nullable, required
  - `full` boolean, required
  - `runId` string, required

## Other responses

- `400`: Validation failed.
- `401`: Missing or unknown bearer key.
- `403`: The key lacks the required scope.
- `404`: No such resource in this tenant.
- `409`: State conflict — e.g. a lost/mismatched claim token, an already claimed work item, or an immutable-version republish.

---

[API](https://skmtc.dev/inite/apis/inite-brain-platform-api.md) · [All operations](https://skmtc.dev/inite/apis/inite-brain-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inite/apis/inite-brain-platform-api/revisions/c7c3eb5e304b?raw)