Agents

The Agent resource

An agent represents a single instance of self-hosted runner installed on a customer’s on-prem infrastructure.

An agent resource is automatically created when self-hosted runner connects to the API server to join it agent pool. In order to connect to the pool, the runner requires an agent pool token.

Key path

Description

type* (string)

Available values: agents

id (string)

attributes.created-at (string)

The resource creation timestamp.

attributes.error-message (string)

Contains the error message if the agent is in an errored status.

attributes.last-seen-at (string)

The timestamp when the agent was last seen online.

attributes.name* (string)

The name of the agent. This must be unique within the agent pool.

attributes.os* (string)

The agent’s OS distribution name and version (ex: centos_8, ubuntu_20)

attributes.status (string)

Available values: idle, busy, offline, errored

The agent’s current status

  • busy - The agent is working on a task.

  • errored - The agent has an error and can’t operate correctly. The attribute error-message has the details.

  • idle - The agent is idle and ready to start working on a task.

  • offline - API server hasn’t seen the agent’s heartbeat for 30 seconds.

attributes.version (string)

The agent’s version.

relationships.pool (object)

The agent pool this agent is a member of.

relationships.pool.data.type* (string)

Available values: agent-pools

relationships.pool.data.id* (string)

links.self (string)

List Agents

GET /api/iacp/v3/agents

The endpoint returns a list of agents by various filters.

Query Parameters
  • filter[agent] (string) – The agent identifier.

  • filter[agent-pool] (string) – The agent pool identifier.

  • filter[agent][name] (string) – The agent name.

  • page[number] (string) – Page number

  • page[size] (string) – Page size

  • include (array) – The comma-separated list of relationship paths. (Available values: pool)

  • sort (array) – The comma-separated list of attributes. (Available values: last-seen-at, name, os, pool, status, version)

Example Request:

GET /api/iacp/v3/agents HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Success.

  • 404 Not Found – User not authorized.

  • 4XX – Client error.

  • 5XX – Server error.

Delete an Agent

DELETE /api/iacp/v3/agents/{agent}

This endpoint deletes an agent by ID. Only offline or errored agents can be removed from the pool.

Offline or errored agents will be removed automatically after 7 days of inactivity.

Parameters
  • agent (string) – The ID of the agent to be deleted.

Status Codes
  • 204 No Content – Deleted.

  • 409 Conflict – The agent is busy and can’t be deleted.

  • 4XX – Client error.

  • 5XX – Server error.

Get an Agent

GET /api/iacp/v3/agents/{agent}

Show details of a specific agent.

Parameters
  • agent (string) – The ID of the agent to show.

Query Parameters
  • include (array) – The comma-separated list of relationship paths. (Available values: pool)

Example Request:

GET /api/iacp/v3/agents/{agent} HTTP/1.1
Host: my.scalr.io
Prefer: profile=preview
Status Codes
  • 200 OK – Success.

  • 404 Not Found – User not authorized or agent not found.

  • 4XX – Client error.

  • 5XX – Server error.