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

# Finish an agent run

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

## Request

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

Closes the run: on `succeeded` a full walk marks what it did not see gone, the delete policy runs over everything gone since the run began, and the checkpoint is recorded; on `failed` the connection records the error. Returns the run summary (also the job_run result). 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
- `runId` string, required

## Request body

- FinishAgentRunRequest
  - `checkpoint` object
  - `error` string
  - `status` 'succeeded' | 'failed', required

## Response `201`

The run summary.

- SourceSyncSummary
  - `changed` integer, required
  - `closed` integer, required
  - `connectionId` string, required
  - `deduplicated` integer, required
  - `durationMs` integer, required
  - `error` string
  - `failed` integer, required
  - `fetched` integer, required
  - `gone` integer, required
  - `ingested` integer, required
  - `mode` 'full' | 'incremental', required
  - `new` integer, required
  - `principals` object
    - `accounts` integer, required
    - `changed` boolean, required
    - `epoch` integer, required
    - `groups` integer, required
    - `linked` integer, required
  - `seen` integer, required
  - `skipped` string
  - `status` 'succeeded' | 'failed' | 'skipped', required
  - `unchanged` integer, 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)