An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose.A workspace may be configured to use one of the organization's agent pools to run remote operations with isolated,private, or on-premises infrastructure.
List Agent Pools
GET /organizations/:organization_name/agent-pools
Parameter
Description
:organization_name
The name of the organization.
This endpoint allows you to list agent pools, their agents, and their tokens for an organization.
This endpoint supports paginationwith standard URL query parameters. Remember to percent-encode[ as%5B and] as%5D if your tooling doesn't automatically encode URLs.
Parameter
Description
q
Optional. A search query string. Agent pools are searchable by name.
sort
Optional. Allows sorting the returned agents pools. Valid values are"name" and"created-at". Prepending a hyphen to the sort parameter will reverse the order (e.g."-name").
page[number]
Optional. If omitted, the endpoint will return the first page.
page[size]
Optional. If omitted, the endpoint will return 20 agent pools per page.
filter[allowed_workspaces][name]
Optional. Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer toScoping Agent Pools to Specific Workspaces.
Response fields
Responses for this endpoint can contain anattributes object with the following fields:
Field name
Type
Description
data.attributes.agent-count
number
The number of agents inIdle,Busy orUnknown states. Agents that areExited orErrored are excluded.
data.attributes.meta.status-counts.total
number
The total number of resources the filter was applied to.
data.attributes.meta.status-counts.matching
number
The total number of resources returned, which match the filter you applied.
Agent Pool not found, or user unauthorized to perform action
Query Parameters
This endpoint supports paginationwith standard URL query parameters. Remember to percent-encode[ as%5B and] as%5D if your tooling doesn't automatically encode URLs.
Parameter
Description
filter[last-ping-since]
Optional. Accepts a date in ISO8601 format (ex.2020-08-11T10:41:23Z).
page[number]
Optional. If omitted, the endpoint will return the first page.
page[size]
Optional. If omitted, the endpoint will return 20 agents per page.
Malformed request body (missing attributes, wrong types, etc.)
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path
Type
Default
Description
data.type
string
Must be"agent-pools".
data.attributes.name
string
The name of the agent pool, which can only include letters, numbers,-, and_. This will be used as an identifier and must be unique in the organization.
data.attributes.organization-scoped
bool
true
The scope of the agent pool. If true, all workspaces in the organization can use the agent pool.
Malformed request body (missing attributes, wrong types, etc.)
Request Body
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path
Type
Default
Description
data.type
string
Must be"agent-pools".
data.attributes.name
string
(previous value)
The name of the agent pool, which can only include letters, numbers,-, and_. This will be used as an identifier and must be unique in the organization.
data.attributes.organization-scoped
bool
true
The scope of the agent pool. If true, all workspaces in the organization can use the agent pool.
The GET endpoints above can optionally return related resources, if requested withtheinclude query parameter. The following resource types are available: