GET /scopes/task_targets/<task-target-id>

On this page:

Get information about a specific task-target.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include an integer identifying a specific task-target For example, this request queries a task-target with ID 375:

https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/375

Task-target IDs are returned in responses from the POST /command/task_target and GET /scopes/task_targets endpoints.

Response format

The response is a JSON object that uses the following keys to provide details about the task-target:

Key	Definition
`id`	The task-target's absolute URL, which includes the task-target's numerical ID.
`name`	A stringified number identifying the task-target.
`display_name`	The task-target's human-readable name. Multiple task-targets can have the same display name.
`tasks`	An array of tasks that the task-target can run. Omitted if `all_tasks` is `true`.
`all_tasks`	A Boolean indicating whether the task-target can run any tasks on designated node targets. If `tasks` is specified, then `all_tasks` is `false`. If `tasks` is omitted, then `all_tasks` is `true`.
`nodes`	An array of certnames identifying nodes the task-target can run tasks on. It can be empty. Combines with `node_groups` and `pql_query` to form a total node pool.
`node_groups`	An array of node group IDs identifying node groups the task-target can run tasks on. It can be empty. Combines with `nodes` and `pql_query` to form a total node pool.
`pql_query`	A string specifying a single PQL query identifying nodes the task-target can run tasks on. Omitted if empty. Combines with `nodes` and `node_groups` to form a total node pool.

For information about how these keys are set and possible values for each key, refer to the POST /command/task_target endpoint.

For example:

{
  "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/1",
  "name": "1",
  "tasks": [
    "package::install",
    "exec"
  ],
  "all_tasks": "false",
  "nodes": [
    "wss6c3w9wngpycg",
    "jjj2h5w8gpycgwn"
  ],
  "node_groups":[
    "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
    "4932bfe7-69c4-412f-b15c-ac0a7c2883f1"
  ],
  "pql_query": "nodes[certname] { catalog_environment = \"production\" }"
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 404 puppetlabs.orchestrator/unknown-task-target response if the specified task-target ID doesn't match any existing task-target IDs.