GET /scopes/task_targets

Retrieve information about all orchestrator task-targets.

Request format

When Forming orchestrator API requests to this endpoint, the request is a basic call, such as:

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

The GET /scopes/task_targets endpoint does not support any parameters; however, as with other orchestrator API endpoints, you must provide authentication.

The GET /scopes/task_targets endpoint returns information about all known task-targets. When there are many task-targets, the response body contains lots of data. For shorter responses, you can use the GET /scopes/task_targets/<task-target-id> endpoint to query a specific task-target, if you know the task-target's ID.

Response format

A successful response is a JSON object containing an array of task-targets. The following keys are used to provide information about each 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, this response describes three task-targets:

{
 "items": [
    {
      "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\" }"
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/2",
      "name": "2",
      "tasks": [
        "imaginary::task"
      ],
      "all_tasks": "false",
      "nodes": [
        "mynode"
      ],
      "node_groups":[
      ]
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/scopes/task_targets/3",
      "name": "3",
      "all_tasks": true,
      "nodes": [
        "xxx6c3w9wngpycg",
        "bbb2h5w8gpycgwn"
      ],
      "node_groups":[
        "3c4df64f-7609-4d31-9c2d-acfa52ed66ec",
        "4932bfe7-69c4-412f-b15c-ac0a7c2883f1"
      ]
    }
  ]
}

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses.