REST API endpoints for self-hosted runners - GitHub Enterprise Server 3.22 Docs

List self-hosted runners for an enterprise

Lists all self-hosted runners configured for an enterprise.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "List self-hosted runners for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List self-hosted runners for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Query parameters
Name, Type, Description
`name` string The name of a self-hosted runner.
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List self-hosted runners for an enterprise"

Status code	Description
`200`	OK

Code samples for "List self-hosted runners for an enterprise"

Request example

get/enterprises/{enterprise}/actions/runners

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners

Response

Status: 200

{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true,
      "ephemeral": false,
      "version": "2.323.0",
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 11,
          "name": "Linux",
          "type": "read-only"
        }
      ]
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false,
      "ephemeral": false,
      "version": "2.323.0",
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 20,
          "name": "macOS",
          "type": "read-only"
        },
        {
          "id": 21,
          "name": "no-gpu",
          "type": "custom"
        }
      ]
    }
  ]
}

List runner applications for an enterprise

Lists binaries for the runner application that you can download and run.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "List runner applications for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List runner applications for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "List runner applications for an enterprise"

Status code	Description
`200`	OK

Code samples for "List runner applications for an enterprise"

Request example

get/enterprises/{enterprise}/actions/runners/downloads

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/downloads

Response

Status: 200

[
  {
    "os": "osx",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-osx-x64-2.277.1.tar.gz",
    "filename": "actions-runner-osx-x64-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "f1fa173889dc9036cd529417e652e1729e5a3f4d35ec0151806d7480fda6b89b"
  },
  {
    "os": "linux",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-linux-x64-2.277.1.tar.gz",
    "filename": "actions-runner-linux-x64-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "02d710fc9e0008e641274bb7da7fde61f7c9aa1cbb541a2990d3450cc88f4e98"
  },
  {
    "os": "linux",
    "architecture": "arm",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-linux-arm-2.277.1.tar.gz",
    "filename": "actions-runner-linux-arm-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIyYTEzZDRmZC01ZDhkLTRjNzgtYjg2MS0zYTMxZGQ3MmYzNjQiLCJzaWQiOiI0MzZiNTg3YS04ODMyLTRiMTMtOWM2Ny05OWRkMjA2ZTQzNmMiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MzE1NzEsImV4cCI6MTYxNzkzNTc3MX0.PMhU7-MOnZRDj5k5a4ieeFlQCmKPl2pQvpVRhGZq-9ByKF5s9G0rsnGBxDcolTYlbvEAmSSkeAEwF486F7P0kMVEb-GI14WbErqqMSyaPL81c3W7UHxMJLaSBnDs9ftHMv_IkJmRzaROS8q1ObzUW-ErlltxCdj2zF_5ruK9G2RR566AOAtiA3AHV6k7-FCY5--sDYJN_YXPgpwI0fPN1TM92fdPm93hJnoXuCJNpBYp1vl5W4gwGtU_Pa07ESdqqFN1YJJHUloedNhiIOczGfGVSapRc8vyGm9P_VCM_yKD8JI-MkOXl8JI5fCfhmjmKsw-vSAh9NW67RGvmehmpw",
    "sha256_checksum": "2f2bda21e2fd8fed6938b33182a293f6b1f74e4c5d09acd6d9a0fe3f979f5c85"
  },
  {
    "os": "win",
    "architecture": "x64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-win-x64-2.277.1.zip",
    "filename": "actions-runner-win-x64-2.277.1.zip",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "7215c75a462eeb6a839fa8ed298d79f620617d44d47d37c583114fc3f3b27b30"
  },
  {
    "os": "linux",
    "architecture": "arm64",
    "download_url": "https://github.com/actions/runner/releases/download/v2.277.1/actions-runner-linux-arm64-2.277.1.tar.gz",
    "filename": "actions-runner-linux-arm64-2.277.1.tar.gz",
    "temp_download_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkJmSjdCUXpLdXhjWDc4WnJ5NUxnUW53ZFRrMCJ9.eyJuYW1laWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzY3AiOiJBY3Rpb25zUnVudGltZS5QYWNrYWdlRG93bmxvYWQiLCJJZGVudGl0eVR5cGVDbGFpbSI6IlN5c3RlbTpTZXJ2aWNlSWRlbnRpdHkiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9zaWQiOiJERERERERERC1ERERELUREREQtRERERC1EREREREREREREREQiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3ByaW1hcnlzaWQiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJhdWkiOiIwZTZkODAxYi02NzVlLTQ1YzAtOWM4NC1jYTkzNjdlZjc1NjciLCJzaWQiOiI4ZTE5MDliZC1kYzU1LTQ2MWYtOTk2Mi1hZTI0OTEzNzU4OWIiLCJpc3MiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJhdWQiOiJ2c3Rva2VuLmNvZGVkZXYubXMiLCJuYmYiOjE2MTc5MDQxNzUsImV4cCI6MTYxNzkwODM3NX0.YNsRXL9pBuIfLVndnyVQOpru77Br8hgYIX7LPsOaMfKk4K88YG89a2VIXUWPyHRiOaC-4J0lIPei8ujezEtnMfNZCwHdWq0Niiy-2-ywcfGPmcz-RHz_ZglkPFbzKaiZWJcFKCGHCP0Ta3kdXumJQqiVJEIyppxIY-caR_Wsw2L4BZHOefJq-odsJ0guPgm9fVuU9FxVRkucho1UH_bzt0tAMl1gEWOLBLZ88U9LKCzHWaxheFeBV4DTt1lAcSm213gKP1eMbgAGn5heWhR4RMRBzZc2HO3Lf1syu4E8fW8a-esRAxEYPfqPHwN9LNj2jaU3D3nPwa8lHQLLtA1PNA",
    "sha256_checksum": "a6aa6dd0ba217118ef2b4ea24e9e0a85b02b13c38052a5de0776d6ced3a79c64"
  }
]

Create configuration for a just-in-time runner for an Enterprise

Generates a configuration that can be passed to the runner application at startup.

OAuth tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Create configuration for a just-in-time runner for an Enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create configuration for a just-in-time runner for an Enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Body parameters
Name, Type, Description
`name` string Required The name of the new runner.
`runner_group_id` integer Required The ID of the runner group to register the runner to.
`labels` array of strings Required The names of the custom labels to add to the runner. Minimum items: 1. Maximum items: 100.
`work_folder` string The working directory to be used for job execution, relative to the runner install directory. Default: `_work`

HTTP response status codes for "Create configuration for a just-in-time runner for an Enterprise"

Status code	Description
`201`	Created
`404`	Resource not found
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create configuration for a just-in-time runner for an Enterprise"

Request example

post/enterprises/{enterprise}/actions/runners/generate-jitconfig

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/generate-jitconfig \
  -d '{"name":"New runner","runner_group_id":1,"labels":["self-hosted","X64","macOS","no-gpu"],"work_folder":"_work"}'

Response

Status: 201

{
  "runner": {
    "id": 23,
    "name": "New runner",
    "os": "unknown",
    "status": "offline",
    "busy": false,
    "labels": [
      {
        "id": 5,
        "name": "self-hosted",
        "type": "read-only"
      },
      {
        "id": 7,
        "name": "X64",
        "type": "read-only"
      },
      {
        "id": 20,
        "name": "macOS",
        "type": "read-only"
      },
      {
        "id": 21,
        "name": "no-gpu",
        "type": "custom"
      }
    ]
  },
  "encoded_jit_config": "abc123"
}

Create a registration token for an enterprise

Returns a token that you can pass to the config script. The token expires after one hour.

Example using registration token:

Configure your self-hosted runner, replacing TOKEN with the registration token provided by this endpoint.

./config.sh --url https://github.com/enterprises/octo-enterprise --token TOKEN

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Create a registration token for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create a registration token for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "Create a registration token for an enterprise"

Status code	Description
`201`	Created

Code samples for "Create a registration token for an enterprise"

Request example

post/enterprises/{enterprise}/actions/runners/registration-token

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/registration-token

Response

Status: 201

{
  "token": "LLBF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-22T12:13:35.123-08:00"
}

Create a remove token for an enterprise

Returns a token that you can pass to the config script to remove a self-hosted runner from an enterprise. The token expires after one hour.

Example using remove token:

To remove your self-hosted runner from an enterprise, replace TOKEN with the remove token provided by this endpoint.

./config.sh remove --token TOKEN

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Create a remove token for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create a remove token for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "Create a remove token for an enterprise"

Status code	Description
`201`	Created

Code samples for "Create a remove token for an enterprise"

Request example

post/enterprises/{enterprise}/actions/runners/remove-token

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/remove-token

Response

Status: 201

{
  "token": "AABF3JGZDX3P5PMEXLND6TS6FCWO6",
  "expires_at": "2020-01-29T12:13:35.123-08:00"
}

Get a self-hosted runner for an enterprise

Gets a specific self-hosted runner configured in an enterprise.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Get a self-hosted runner for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Get a self-hosted runner for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.

HTTP response status codes for "Get a self-hosted runner for an enterprise"

Status code	Description
`200`	OK

Code samples for "Get a self-hosted runner for an enterprise"

Request example

get/enterprises/{enterprise}/actions/runners/{runner_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID

Response

Status: 200

{
  "id": 23,
  "name": "MBP",
  "os": "macos",
  "status": "online",
  "busy": true,
  "ephemeral": false,
  "version": "2.323.0",
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Delete a self-hosted runner from an enterprise

Forces the removal of a self-hosted runner from an enterprise. You can use this endpoint to completely remove the runner when the machine you were using no longer exists.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Delete a self-hosted runner from an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Delete a self-hosted runner from an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.

HTTP response status codes for "Delete a self-hosted runner from an enterprise"

Status code	Description
`204`	No Content
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Delete a self-hosted runner from an enterprise"

Request example

delete/enterprises/{enterprise}/actions/runners/{runner_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID

Response

Status: 204

List labels for a self-hosted runner for an enterprise

Lists all labels for a self-hosted runner configured in an enterprise.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "List labels for a self-hosted runner for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List labels for a self-hosted runner for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.

HTTP response status codes for "List labels for a self-hosted runner for an enterprise"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "List labels for a self-hosted runner for an enterprise"

Request example

get/enterprises/{enterprise}/actions/runners/{runner_id}/labels

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID/labels

Response

Status: 200

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Add custom labels to a self-hosted runner for an enterprise

Add custom labels to a self-hosted runner configured in an enterprise.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Add custom labels to a self-hosted runner for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Add custom labels to a self-hosted runner for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.

Body parameters
Name, Type, Description
`labels` array of strings Required The names of the custom labels to add to the runner.

HTTP response status codes for "Add custom labels to a self-hosted runner for an enterprise"

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Add custom labels to a self-hosted runner for an enterprise"

Request example

post/enterprises/{enterprise}/actions/runners/{runner_id}/labels

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID/labels \
  -d '{"labels":["gpu","accelerated"]}'

Response

Status: 200

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Set custom labels for a self-hosted runner for an enterprise

Remove all previous custom labels and set the new custom labels for a specific self-hosted runner configured in an enterprise.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Set custom labels for a self-hosted runner for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Set custom labels for a self-hosted runner for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.

Body parameters
Name, Type, Description
`labels` array of strings Required The names of the custom labels to set for the runner. You can pass an empty array to remove all custom labels.

HTTP response status codes for "Set custom labels for a self-hosted runner for an enterprise"

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Set custom labels for a self-hosted runner for an enterprise"

Request example

put/enterprises/{enterprise}/actions/runners/{runner_id}/labels

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID/labels \
  -d '{"labels":["gpu","accelerated"]}'

Response

Status: 200

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

Remove all custom labels from a self-hosted runner for an enterprise

Remove all custom labels from a self-hosted runner configured in an enterprise. Returns the remaining read-only labels from the runner.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Remove all custom labels from a self-hosted runner for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Remove all custom labels from a self-hosted runner for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.

HTTP response status codes for "Remove all custom labels from a self-hosted runner for an enterprise"

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Remove all custom labels from a self-hosted runner for an enterprise"

Request example

delete/enterprises/{enterprise}/actions/runners/{runner_id}/labels

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID/labels

Response

Status: 200

{
  "total_count": 3,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    }
  ]
}

Remove a custom label from a self-hosted runner for an enterprise

Remove a custom label from a self-hosted runner configured in an enterprise. Returns the remaining labels from the runner.

This endpoint returns a 404 Not Found status if the custom label is not present on the runner.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Remove a custom label from a self-hosted runner for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Remove a custom label from a self-hosted runner for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_id` integer Required Unique identifier of the self-hosted runner.
`name` string Required The name of a self-hosted runner's custom label.

HTTP response status codes for "Remove a custom label from a self-hosted runner for an enterprise"

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Remove a custom label from a self-hosted runner for an enterprise"

Request example

delete/enterprises/{enterprise}/actions/runners/{runner_id}/labels/{name}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runners/RUNNER_ID/labels/NAME

Response

Status: 200

{
  "total_count": 4,
  "labels": [
    {
      "id": 5,
      "name": "self-hosted",
      "type": "read-only"
    },
    {
      "id": 7,
      "name": "X64",
      "type": "read-only"
    },
    {
      "id": 20,
      "name": "macOS",
      "type": "read-only"
    },
    {
      "id": 21,
      "name": "no-gpu",
      "type": "custom"
    }
  ]
}

List self-hosted runners for an organization

Lists all self-hosted runners configured in an organization.

Authenticated users must have admin access to the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the admin:org scope to use this endpoint. If the repository is private, the repo scope is also required.

Fine-grained access tokens for "List self-hosted runners for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Self-hosted runners" organization permissions (read)

Parameters for "List self-hosted runners for an organization"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Query parameters
Name, Type, Description
`name` string The name of a self-hosted runner.
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "List self-hosted runners for an organization"

Status code	Description
`200`	OK

Code samples for "List self-hosted runners for an organization"

Request example

get/orgs/{org}/actions/runners

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/actions/runners

Response

Status: 200

{
  "total_count": 2,
  "runners": [
    {
      "id": 23,
      "name": "linux_runner",
      "os": "linux",
      "status": "online",
      "busy": true,
      "ephemeral": false,
      "version": "2.323.0",
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 11,
          "name": "Linux",
          "type": "read-only"
        }
      ]
    },
    {
      "id": 24,
      "name": "mac_runner",
      "os": "macos",
      "status": "offline",
      "busy": false,
      "ephemeral": false,
      "version": "2.323.0",
      "labels": [
        {
          "id": 5,
          "name": "self-hosted",
          "type": "read-only"
        },
        {
          "id": 7,
          "name": "X64",
          "type": "read-only"
        },
        {
          "id": 20,
          "name": "macOS",
          "type": "read-only"
        },
        {
          "id": 21,
          "name": "no-gpu",
          "type": "custom"
        }
      ]
    }
  ]
}