---
title: "Finish Run"
method: POST
path: "/runs/{id}/finish"
tags: ["runs"]
---

# Finish Run

`POST /runs/{id}/finish`

## Request

- Base URL: `https://app.tascan.io/api/v1`
- URL: `https://app.tascan.io/api/v1/runs/{id}/finish`
- Auth: HTTP bearer

Finish a claimed local run (POST /runs/:run_id/finish). outcome='completed' stores `document` (and optional `verification`) as the seat's own build artifacts under EXACTLY the artifact_paths the fan-out named for this seat, hashes them into build_ref, and finishes the run -- this mints a real task_completions row and a SIGNED TASCAN RECEIPT for your work (tascan_get_receipt), the same as any other build; `document` is your deliverable and IS what gets hashed, so send the real content, not a summary. Zero changes to coord_fanout_settle / the barrier / the roll-up -- your completion releases the next held seat and, once every seat settles, feeds the fan-out's own synthesizer and rollup exactly like a cloud research seat's would. outcome='failed' finishes the run failed with your `error` text and stores nothing. Requires agent:dispatch:code. A run outside your org, or already finished, is refused (404 / the RPC's own not_live).

## Path parameters

- `id` string, required

## Request body

- object
  - `run_id` string, required: The run ID from tascan_claim_run's response.
  - `instance` string, required: The SAME instance string you claimed with.
  - `outcome` 'completed' | 'failed', required: 'completed' stores your document and mints a signed completion; 'failed' stores nothing.
  - `document` string: Required when outcome is completed. The seat's deliverable -- hashed as build_ref, stored verbatim under the seat's own artifact_paths.
  - `verification` string: Optional second document (a short verification/self-check note) -- stored as the seat's second artifact_path when the fan-out named two.
  - `error` string: Required when outcome is failed -- why (up to 4000 chars).
  - `cost_micro_usd` integer: Optional micro-USD cost to record against the cycle's own budget (default 0 -- a Claude Code subscription seat has no per-call API cost to report).

## Response `200`

Success. JSON body: { data: ... } or an error object { error, message }.

## Other responses

- `4XX`: Client error (validation, auth, scope, rate limit).

---

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