CoderHelm Docs
APIRuns

Get a run

GET
/api/runs/{run_id}

Returns one run in full: its status and current step, the pull requests and branches it opened, the files it changed, token use and cost, and the notes it wrote while working. Poll it to follow a run; a few seconds apart is plenty.

Authorization

api_key view
headerAuthorizationBearer <token>

A team API key, made by an admin under Settings, API keys. Send it as Authorization: Bearer chk_....

Scope: view

Path Parameters

run_id*string

The run's id.

Response Body

The run.

application/json
  1. response

One run, in full.

applied_standards*array<string>

The team standards the run was given in full ("always apply").

Example
[  "api-error-format"]
branch?|

The branch the run pushed.

Example"coderhelm/web-42-login-rate-limit"
branches?array<string>|

Their branches, in the same order.

Example
[  "coderhelm/web-42-login-rate-limit"]
cache_read_tokens*integer

Tokens read from the prompt cache.

Formatint64
Range0 <= value
Example905112
cache_write_tokens*integer

Tokens written to the prompt cache.

Formatint64
Range0 <= value
Example64002
close_reason?|

Why it was closed.

Examplenull
closed_at?|

When it was closed (RFC 3339).

Examplenull
closed_by?|

Who closed the run on purpose.

Examplenull
closed_from?|

The status it had when it was closed.

Examplenull
cost_usd*number

What the run cost in model usage, in US dollars, as recorded.

Formatdouble
Example1.42
created_at?|

When the run started (RFC 3339).

Example"2026-10-22T14:03:11Z"
current_pass?|

The step the run is on or ended on.

Example"pr"
duration_s?|

How long the run took, in seconds.

Formatint64
Range0 <= value
Example734
error?|

Why the run failed, when it did.

Examplenull
files_modified?array<string>|

The files the run changed.

Example
[  "src/auth/login.ts",  "src/auth/login.test.ts"]
fix_location?|

Where the fix belongs: code, or somewhere outside the code.

Example"code"
lesson?|

A lesson recorded for the repository when the fix was elsewhere.

Examplenull
mcp_servers?array<string>|

The MCP servers the run used.

Example[]
outside_change_report?|

The report written when (part of) the fix is a change outside the code.

Examplenull
pass_history?array<>|

The steps it went through, in order.

Example
[  {    "pass": "triage",    "started_at": "2026-10-22T14:03:11Z"  },  {    "pass": "implement",    "started_at": "2026-10-22T14:05:40Z"  },  {    "pass": "pr",    "started_at": "2026-10-22T14:14:50Z"  }]
pr_number?|

That pull request's number.

Formatint64
Range0 <= value
Example318
pr_numbers?array<>|

Their numbers, in the same order.

Example
[  318]
pr_url?|

The pull request the run opened.

Example"https://github.com/acme/web/pull/318"
pr_urls?array<string>|

Every pull request, when the work spans several repositories.

Example
[  "https://github.com/acme/web/pull/318"]
progress_notes?array<>|

Notes it wrote while working, in order.

Example
[  {    "message": "Tests pass; opening the pull request.",    "timestamp": "2026-10-22T14:15:02Z"  }]
repo?|

The repository, owner/name.

Example"acme/web"
status?|

Where the run is: pending, running, awaiting_ci, completed, failed, needs_input, needs_outside_change, cancelled, retried or closed. Treat a value you don't know as in progress.

Example"completed"
ticket_id?|

The ticket's key or issue number in its source.

Example"WEB-42"
ticket_source?|

What started it, such as github, jira or alert.

Example"jira"
title?|

The ticket's title.

Example"Add rate limiting to the login form"
tokens_in*integer

Input tokens, not counting cache reads and writes.

Formatint64
Range0 <= value
Example182340
tokens_out*integer

Output tokens.

Formatint64
Range0 <= value
Example20511
updated_at?|

When it last changed (RFC 3339).

Example"2026-10-22T14:15:25Z"
curl -X GET 'https://api.coderhelm.com/api/runs/01JB8X6F4M2C9QZ3T7V5W1K0HA' \  -H "Authorization: Bearer $CODERHELM_API_KEY"
{  "applied_standards": [    "api-error-format"  ],  "branch": "coderhelm/web-42-login-rate-limit",  "branches": [    "coderhelm/web-42-login-rate-limit"  ],  "cache_read_tokens": 905112,  "cache_write_tokens": 64002,  "close_reason": null,  "closed_at": null,  "closed_by": null,  "closed_from": null,  "cost_usd": 1.42,  "created_at": "2026-10-22T14:03:11Z",  "current_pass": "pr",  "duration_s": 734,  "error": null,  "files_modified": [    "src/auth/login.ts",    "src/auth/login.test.ts"  ],  "fix_location": "code",  "lesson": null,  "mcp_servers": [],  "outside_change_report": null,  "pass_history": [    {      "pass": "triage",      "started_at": "2026-10-22T14:03:11Z"    },    {      "pass": "implement",      "started_at": "2026-10-22T14:05:40Z"    },    {      "pass": "pr",      "started_at": "2026-10-22T14:14:50Z"    }  ],  "pr_number": 318,  "pr_numbers": [    318  ],  "pr_url": "https://github.com/acme/web/pull/318",  "pr_urls": [    "https://github.com/acme/web/pull/318"  ],  "progress_notes": [    {      "message": "Tests pass; opening the pull request.",      "timestamp": "2026-10-22T14:15:02Z"    }  ],  "repo": "acme/web",  "status": "completed",  "ticket_id": "WEB-42",  "ticket_source": "jira",  "title": "Add rate limiting to the login form",  "tokens_in": 182340,  "tokens_out": 20511,  "updated_at": "2026-10-22T14:15:25Z"}
Edit on GitHub

List runs GET

Lists the team's runs, newest first, one page at a time. Search with `q` and filter by `status`, `source` and `repo`. Each page reads at most a few hundred runs, so a page can come back short, or empty, with `next` set: keep reading until `next` is null.

Cancel a run POST

Stops a run that is `running`. The run becomes `cancelled`, and the work it has not done yet is dropped; a pull request it already opened stays open. A run in any other state answers `400`, so cancelling twice is harmless.