Skip to content

Query all K8S runners under the specified repository

GET /api/v8/repos/{owner}/{repo}/actions/runner-sets

Query all K8S runners under the specified repository (RunnerSet); keyword filtering and paginated results are supported.

Access token support

  • AtomGit user access tokens

Anonymous access

This endpoint does not allow anonymous access.

Request parameters

Parameter Location Type Required Description
owner path string Yes Address path of the namespace that owns the repository (organization or personal address path)
repo path string Yes Repository path (path)
access_token query string Yes User authorization code
keyword query string No Keyword filter
page query integer No Current page number, default 1; must be a positive integer
per_page query integer No Number of items per page, default 10; must be a positive integer

Response parameters

Field Type Always returned Nullable Description
total_count integer Yes No RunnerSet total
runner_sets array Yes Yes RunnerSet list

runner_sets array element object

Field Type Always returned Nullable Description
runner_sets.id string Yes No RunnerSet ID
runner_sets.runner_group_id string Yes No Runner Group ID
runner_sets.name string Yes No Name
runner_sets.status string Yes No State; enum: using (in use) / wait_release (releasing)
runner_sets.required_labels array Yes Yes Required labels
runner_sets.min_runner_size integer Yes No Minimum runner count
runner_sets.max_runner_size integer Yes No Maximum runner count
runner_sets.limit_cpu integer Yes No CPU limit
runner_sets.limit_memory integer Yes No Memory limit
runner_sets.image_name string Yes No Image name
runner_sets.user_k8s_cluster_id string Yes No User K8S cluster ID
runner_sets.user_k8s_cluster_name string Yes No User K8S cluster name
runner_sets.user_k8s_resource_type string Yes No User K8S resource type
runner_sets.user_k8s_cluster_namespace string Yes No User K8S namespace
runner_sets.user_k8s_url string Yes No User K8S address
runner_sets.create_time integer Yes No Creation time
runner_sets.update_time integer Yes No Update time
runner_sets.user_id string Yes No User ID
runner_sets.user_name string Yes No Username
runner_sets.user_project_id string Yes No User project ID

runner_sets.required_labels array element object

Field Type Always returned Nullable Description
runner_sets.required_labels.label_name string Yes No Label name
runner_sets.required_labels.label_value string Yes No Label value
runner_sets.required_labels.label_color string Yes No Label color

Error responses

This endpoint requires authentication and the read_action permission, and may return the following failure responses:

400 Invalid parameters

{
  "error": "invalid_request",
  "message": "The format of the page parameter is invalid"
}

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "Insufficient permission; the read_action permission is required"
}

Note: The field names of the failure responses above are subject to what the backend actually returns.

HTTP response status codes

Status code Description
200 Success (OK)
400 Bad Request
401 Requires authentication
403 Forbidden
404 Repository or resource not found (Not Found)

Request example

Parameter notes

<owner> is replaced with the address path of the namespace that owns the repository (organization or personal address path); <repo> is replaced with the repository path; <token> is replaced with your AtomGit user access token.

cURL

curl -X GET 'https://api.atomgit.com/api/v8/repos/<owner>/<repo>/actions/runner-sets?access_token=<token>&page=1&per_page=10' \
  -H 'Accept: application/json'

JavaScript

// Native fetch (Node.js 18+ / browser)
const response = await fetch("https://api.atomgit.com/api/v8/repos/<owner>/<repo>/actions/runner-sets?access_token=<token>&page=1&per_page=10", {
  headers: {
    "Accept": "application/json",
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python

import requests

resp = requests.get(
    "https://api.atomgit.com/api/v8/repos/<owner>/<repo>/actions/runner-sets",
    params={"access_token": "<token>", "page": 1, "per_page": 10},
    headers={"Accept": "application/json"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example

Status code: 200

{
  "total_count": 1,
  "runner_sets": [
    {
      "id": "rs-123456",
      "runner_group_id": "rg-1001",
      "name": "k8s-runner-set-01",
      "status": "using",
      "required_labels": [
        {
          "label_name": "runner-type",
          "label_value": "k8s",
          "label_color": "blue"
        }
      ],
      "min_runner_size": 1,
      "max_runner_size": 5,
      "limit_cpu": 4,
      "limit_memory": 8192,
      "image_name": "ubuntu:22.04",
      "user_k8s_cluster_id": "cluster-01",
      "user_k8s_cluster_name": "prod-cluster",
      "user_k8s_resource_type": "Deployment",
      "user_k8s_cluster_namespace": "default",
      "user_k8s_url": "https://api.atomgit.com",
      "create_time": 1720000000,
      "update_time": 1720000000,
      "user_id": "u-001",
      "user_name": "octocat",
      "user_project_id": "p-001"
    }
  ]
}

Error codes

Error code Description
401 Unauthenticated or invalid credentials (missing or invalid access token)
400 Invalid parameters or the request could not be parsed
403 Insufficient permission; the read_action permission is required
404 The request path or repository does not exist
429 Too many requests; rate limit triggered
500 Internal server error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc