GET /scheduled_jobs/environment_jobs

Retrieve information about scheduled environment jobs, which are deployments, tasks, or plans that run in a specific environment. Use parameters to narrow the response scope.

Request format

When Forming orchestrator API requests to this endpoint, you can append optional parameters to the end of the URI path, such as:

https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs?limit=50&type=task

These parameters are available:

Parameter	Definition
limit	Set the maximum number of scheduled jobs to include in the response. The point at which the limit count starts is determined by offset, and the job record sort order is determined by order_by and order.
offset	Specify a zero-indexed integer at which to start returning results. For example, if you set this to 12, the response returns scheduled jobs starting with the 13th record. The default is 0.
order_by	Specify one of the following categories to use to sort the results: next_run_time, environment, owner, name, or type. The default is next_run_time.
order	Indicate whether results are returned in ascending (asc) or descending (desc) order. The default is asc.
type	Specify a job type to query, either deploy, task, or plan.

Response format

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

The items array contains a JSON object for each scheduled job. Each object can use these keys to provide job details:

Key	Definition
id	The job's absolute URL, which includes the job's numerical ID.
name	The job's numerical ID as a stringified number.
enabled	A Boolean indicating whether the job is enabled.
environment	The environment that the job operates in.
owner	The subject ID, email, and other details of the user that requested the job.
description	A user-provided description of the job. This can be empty.
type	The job's type, either plan, task, or deploy.
input	An object describing options supplied to the job, including: name: String-formatted project name of the task or plan. parameters: An object containing key-value pairs of non-sensitive parameters and values supplied to the job. sensitive_parameters: An array of names of sensitive parameters supplied to the job.
userdata	An object containing arbitrary key-value pairs supplied by the initiating user, if any were supplied.
schedule	An object describing the job's schedule, including: start_time: An ISO-8601 timestamp indicating the first time the job ran (or will run). interval: An object representing the frequency at which the job runs, such as every 1300 seconds.
next_run	An object containing an ISO-8601 timestamp indicating the scheduled job's next run time.
last_run	If the job has not yet run, this is null. If the job has run, this is an object containing an ISO-8601 timestamp of the scheduled job's most recent run time and a job object. The job object can contains the submitted job's id or name if the job succeeded. If the job failed, it contains a submission_errorobject describing why the job failed.

The pagination object includes these keys:

• total: The total number of job records in the collection, regardless of limit and offset.
• limit, offset, order_by, order, and type: Reflects values supplied in the request. If you specified a value, these key shows the value you specified. If you did not specify a value, the key shows the default value, if there is one.

This sample response describes two scheduled jobs and the pagination information:

{
  "items": [
    {
      "id": "https://host.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/2",
      "name": "2",
      "environment":  "plan_testing_env",
      "owner": {
        "email": "fred@example.com",
        "login": "fred",
        "display_name": "Fred",
        "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
        "is_revoked": false,
        "last_login": "2020-05-08T15:57:28.444Z",
        "is_remote": true,
        "is_group": false,
        "is_superuser": false,
        "role_ids": [
          1
        ],
        "inherited_role_ids": [
          2
        ],
        "group_ids": [
          "9a588fd8-3daa-4fc2-a396-bf88945def1e"
        ]
      },
      "description": "Fred's scheduled environment plan",
      "type": "plan",
      "next_run": {
        "time": "2021-12-12T19:50:08Z"
      },
      "last_run": {
        "time": "2021-11-12T19:50:08Z",
        "job": {
          "id": "https://host.example.com:8143/orchestrator/v1/plan_jobs/42",
          "name": 42
        }
      },
      "schedule": {
        "start_time": "2018-10-05T19:50:08Z",
        "interval": {
          "value": 3600,
          "units": "seconds"
        }
      },
      "input": {
        "name": "plan_testing_env::example_plan",
        "parameters": {
          "param_1": "foo"
        },
        "sensitive_parameters" : ["password"]
      },
      "userdata": {
        "ticket": "TICKET-123"
      }
    },
    {
      "id": "https://host.example.com:8143/orchestrator/v1/scheduled_jobs/environment_jobs/1",
      "name": "1",
      "environment": "plan_testing_env",
      "owner": {
        "email": "user@example.com",
        "login": "user",
        "display_name": "User",
        "id": "06990bb9-df3a-4150-964f-88b9cf0f8eec",
        "last_login": "2019-07-08T15:57:28.444Z",
        "is_revoked": false,
        "is_remote": true,
        "is_group": false,
        "is_superuser": false,
        "role_ids": [
          1
        ],
        "inherited_role_ids": [
          2
        ],
        "group_ids": [
          "9a588fd8-3daa-4fc2-a396-bf88945def1e"
        ]
      },
      "description": "",
      "type": "plan",
      "schedule": {
        "start_time": "2018-10-05T19:50:08Z",
        "interval": null
      },
      "input": {
        "name": "plan_testing_env::example_plan",
        "parameters": {
          "param_1": "foo"
        },
        "sensitive_parameters" : []
      },
      "userdata": {
        "approval_reference": "442"
      },
      "start_time": "2020-10-05T19:50:08Z",
      "next_run": {
        "time": "2021-12-12T19:50:08Z"
      },
      "last_run": {
        "time": "2021-11-12T19:50:08Z",
        "job": {
          "submission_error": {
              "kind" : "puppetlabs.orchestrator/unknown-environment",
              "msg" : "Unknown environment doesnotexist",
              "details" : {
                "environment" : "doesnotexist"
            }
          },
          "name": 33
        }
      }
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "order": "asc",
    "order_by": "next_run_time",
    "total": 2,
  }
}

Error responses

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

The endpoint returns a 400 puppetlabs.orchestrator/query-error response if you don't have permission to run queries or there is a problem with a supplied parameter, such as the limit or offset parameters not being formatted as integers.