GET /tasks

On this page:

Lists all tasks in a specific environment.

Request format

When Forming orchestrator API requests to this endpoint, you can use the default URI path to query tasks in the production environment, such as:

https://orchestrator.example.com:8143/orchestrator/v1/tasks

For any other environments, you must use the environment parameter to specify the environment whose tasks you want to query. For example, this request queries tasks in the development environment:

https://orchestrator.example.com:8143/orchestrator/v1/plans?environment=development

Response format

The response is a JSON object containing an environment object and a items array.

The environment object contains these keys:

name: The environment specified in the request.
code_id: Either null or a unique string specifying where the environment's tasks are listed. Puppet Server uses the code_id to retrieve the version of file resources in an environment at the time when a catalog was compiled. You can learn more about code_id in the Puppet Static catalogs documentation.

The items array contains one JSON object for each task in the environment. Each task object uses these keys:

Key	Definition
`id`	A URI path you can use with the GET /tasks/<module>/<task-name> endpoint to learn more about the task.
`name`	A stringified number identifying the task. You can use this with, for example, the POST /command/task endpoint.

For example, this response describes three tasks in the production environment:

{
  "environment": {
    "name": "production",
    "code_id": "urn:puppet:code-id:1:a86da166c30f871823f9b2ea224796e834840676;production"
  },
  "items": [
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/install",
      "name": "package::install"
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/package/upgrade",
      "name": "package::upgrade"
    },
    {
      "id": "https://orchestrator.example.com:8143/orchestrator/v1/tasks/exec/init",
      "name": "exec"
    }
  ]
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code	Key	Description
400	`puppetlabs.orchestrator/validation-error`	The `environment` parameter does not supply a legal environment name. For example, the name is not a string or contains illegal characters.
404	`puppetlabs.orchestrator/unknown-environment`	No environment exists that matches the specified environment.