Get runs

Lists what the forge ran for one ref of one repository: each run's workflow, status, conclusion and commit, with its jobs and their steps.

GET /v1/ci/runs/{owner}/{repo}

Ci → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/ci/runs/{owner}/{repo}`
Method	`GET`
Operation	`get_ci_runs_by_owner_by_repo`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Lists what the forge ran for one ref of one repository: each run's workflow, status, conclusion and commit, with its jobs and their steps.

The ref is a branch, a tag or a commit sha, and it is resolved to the commit it names before anything else is read, so the answer is about one commit even while the branch moves. Every run on that commit is listed, newest first, each naming the ref that started it. Read live from git.hanzo.ai, so a tag that exists only on the forge answers the same as a branch.

state is the one-word answer to "is this ref green?": passed, failed, running, queued or none. It is read over the latest attempt of each workflow on the commit; each job also names the runner that took it.

The caller's org decides which namespaces it may read: a SuperAdmin reads any, an org member only the forge namespaces its org owns, and a repository in any other namespace is refused with 403 before the forge is asked. A repository or ref the forge does not have is 404.

Request

3 fields.

Field	In	Type	Required	Description
`owner`	path	string	yes	Owner is the forge namespace the repository lives under, from the path.
`repo`	path	string	yes	Repo is the repository's name, from the path.
`ref`	query	string	—	Ref is a branch, a tag or a commit sha.

Response

Status	Body	Meaning
`200`	ci.Runs	ok
`default`	problem-details	refused

200 body — 32 fields.

Field	In	Type	Always	Description
`ref`	body	string	—	Ref is what was asked for; HEAD when the request named none.
`repo`	body	string	—	Repo is the repository, as owner/name.
`runs`	body	ci.Run[]	—	Runs is every run on that commit, newest first.
`runs[].attempt`	body	integer (int64)	—	Attempt counts re-runs of this run, starting at 1.
`runs[].conclusion`	body	string	—	Conclusion is how it ended — success, failure, cancelled or skipped — and is empty until Status is completed.
`runs[].endedAt`	body	string (date-time)	—	EndedAt is when it finished; absent until it has.
`runs[].event`	body	string	—	Event is what started the run: push, pull_request, workflow_dispatch, schedule.
`runs[].id`	body	integer (int64)	—	ID is the run's id on the forge.
`runs[].jobs`	body	ci.Job[]	—	Jobs are the run's jobs in the order the forge created them.
`runs[].jobs[].conclusion`	body	string	—	Conclusion is how the job ended; empty until it has.
`runs[].jobs[].endedAt`	body	string (date-time)	—	EndedAt is when it finished; absent until it has.
`runs[].jobs[].id`	body	integer (int64)	—	ID is the job's id on the forge.
`runs[].jobs[].name`	body	string	—	Name is the job's name as the workflow declares it.
`runs[].jobs[].runner`	body	string	—	Runner is the name of the runner that took the job; empty until one has.
`runs[].jobs[].startedAt`	body	string (date-time)	—	StartedAt is when the job started; absent until it has.
`runs[].jobs[].status`	body	string	—	Status is whether the job is over, in the same words as the run's.
`runs[].jobs[].steps`	body	ci.Step[]	—	Steps are the job's steps, in order.
`runs[].jobs[].steps[].conclusion`	body	string	—	Conclusion is how the step ended; empty until it has.
`runs[].jobs[].steps[].name`	body	string	—	Name is the step's name as the workflow declares it.
`runs[].jobs[].steps[].number`	body	integer (int64)	—	Number is the step's position in the job, from 1.
`runs[].jobs[].steps[].status`	body	string	—	Status is whether the step is over.
`runs[].jobs[].url`	body	string	—	URL is the job's page on the forge.
`runs[].number`	body	integer (int64)	—	Number is the run's number within the repository, as the forge's page shows it.
`runs[].ref`	body	string	—	Ref is the branch or tag that started the run.
`runs[].sha`	body	string	—	SHA is the commit the run checked out.
`runs[].startedAt`	body	string (date-time)	—	StartedAt is when the run started; absent until it has.
`runs[].status`	body	string	—	Status is whether the run is over: queued, waiting, in_progress or completed.
`runs[].title`	body	string	—	Title is the run's display title, usually the commit's subject.
`runs[].url`	body	string	—	URL is the run's page on the forge.
`runs[].workflow`	body	string	—	Workflow is the workflow file that ran, such as cicd.yml.
`sha`	body	string	—	SHA is the full commit the ref resolved to when it was read.
`state`	body	string	—	State answers "is this ref green?": passed, failed, running, queued or none.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo ci runs owner get <owner> <repo>

.ts

.py

.go

.rs

.java

import { Configuration, CiApi } from 'hanzoai';

const api = new CiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getCiRunsByOwnerByRepo({ owner: 'owner', repo: 'repo' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import CiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = CiApi(client).get_ci_runs_by_owner_by_repo(owner='owner', repo='repo')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.CiAPI.GetCiRunsByOwnerByRepo(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, ci_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = ci_api::get_ci_runs_by_owner_by_repo(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.CiApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new CiApi(client).getCiRunsByOwnerByRepo();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl https://api.hanzo.ai/v1/ci/runs/<owner>/<repo> \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches ci through the ci tool, which names its 2 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_ci_runs"
         }
       }
     }'

Ci API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousList catalog NextList runs