Scheduled jobs endpoints

Use the scheduled_jobs endpoints to query scheduled orchestrator jobs and delete scheduled jobs.

GET /scheduled_jobs

Retrieve information about scheduled jobs.

Request format

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

https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs?limit=20&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`, `scheduled_time`, `name`. The default is `next_run`.
`order`	Indicate whether results are returned in ascending (`asc`) or descending (`desc`) order. The default is `asc`.
`type`	Specify a job type to query. The type matches the command that created the job, which is either `deploy`, `task`, or `plan`.

Response format

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

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 ID.
`name`	The job's name, which may be the same as the ID.
`type`	The job's type, such as `task` or `deploy`.
`task`	The name of the task associated with a scheduled task job
`plan`	The name of the plan associated with a scheduled plan job
`scope`	A list of nodes, a query, or other specification identifying the nodes targeted by the job.
`environment`	The environment that the job operates in.
`owner`	The subject ID, login, and other details of the user that requested the job.
`description`	A user-provided description of the job.
`next_run`	An ISO-8601 timestamp indicating the scheduled job's next run time.
`scheduled_time`	An ISO-8601 timestamp indicating the original scheduled run time.
`schedule_options`	Contains schedule interval information, if this was provided when the job was originally scheduled.
`noop`	A Boolean indicating whether the scheduled job runs in no-op mode. `true`: Runs in no-op mode. `false`: Does not run in no-op mode. This is always `false` for task and plan jobs.
`job_options`	A JSON object containing options supplied to the job.

The pagination object uses 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.

Here is a response example describing four scheduled jobs and pagination information:

{
    "items": [
      {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/1",
        "name": "1",
        "type": "task",
        "task": "echo",
        "scope": {
          "nodes": [
            "east.example.com",
            "west.example.com"
          ]
        },
        "enviroment": "production",
        "owner": {
          "email": "fred@example.com",
          "is_revoked": false,
          "last_login": "2020-05-08T15:57:28.444Z",
          "is_remote": true,
          "login": "fred",
          "inherited_role_ids": [
            2
          ],
          "group_ids": [
            "9a588fd8-3daa-4fc2-a396-bf88945def1e"
          ],
          "is_superuser": false,
          "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
          "role_ids": [
            1
          ],
          "display_name": "Fred",
          "is_group": false
        },
        "description": "rear face the cranfitouser",
        "next_run": "2018-10-12T19:50:08Z",
        "scheduled_time": "2018-10-05T19:50:08Z",
        "schedule_options": {
          "interval": {
            "units": "seconds",
            "value": 604800
          }
        },
        "noop": false,
        "job_options": {
          "noop": false,
          "task": "echo"
        }
      },
      {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/2",
        "name": "2",
        "type": "deploy",
        "scope": {
          "nodes": [
            "east.example.com",
            "west.example.com"
          ]
        },
        "enviroment": "production",
        "owner": {
          "email": "fred@example.com",
          "is_revoked": false,
          "last_login": "2020-05-08T15:57:28.444Z",
          "is_remote": true,
          "login": "fred",
          "inherited_role_ids": [
            2
          ],
          "group_ids": [
            "9a588fd8-3daa-4fc2-a396-bf88945def1e"
          ],
          "is_superuser": false,
          "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
          "role_ids": [
            1
          ],
          "display_name": "Fred",
          "is_group": false
        },
        "description": "middle face the cranfitouser",
        "next_run": "2019-05-05T19:50:08Z",
        "scheduled_time": "2019-05-05T19:50:08Z",
        "schedule_options": {},
        "noop": false,
        "job_options": {
          "noop": false,
          "debug": false,
          "trace": false,
          "no_noop": false,
          "evaltrace": false,
          "concurrency": null,
          "enforce_environment": false
        }
      },
      {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/3",
        "name": "3",
        "type": "task",
        "task": "facter_task",
        "scope": {
          "query": "inventory[certname] { facts.aio_agent_version ~ \"\\\\d+\" }"
        },
        "enviroment": "production",
        "owner": {
          "email": "fred@example.com",
          "is_revoked": false,
          "last_login": "2020-05-08T15:57:28.444Z",
          "is_remote": true,
          "login": "fred",
          "inherited_role_ids": [
            2
          ],
          "group_ids": [
            "9a588fd8-3daa-4fc2-a396-bf88945def1e"
          ],
          "is_superuser": false,
          "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
          "role_ids": [
            1
          ],
          "display_name": "Fred",
          "is_group": false
        },
        "description": "front face the nebaclouser",
        "next_run": "2027-05-05T19:50:08Z",
        "scheduled_time": "2027-05-05T19:50:08Z",
        "schedule_options": {
          "interval": {
            "units": "seconds",
            "value": 86400
          }
        },
        "noop": true,
        "job_options": {
          "noop": true,
          "task": "facter_task"
        }
      },
      {
        "id": "https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs/2",
        "name": "4",
        "type": "plan",
				"plan": "canary::random",
        "scope": {},
        "enviroment": "production",
        "owner": {
          "email": "fred@example.com",
          "is_revoked": false,
          "last_login": "2020-05-08T15:57:28.444Z",
          "is_remote": true,
          "login": "fred",
          "inherited_role_ids": [
            2
          ],
          "group_ids": [
            "9a588fd8-3daa-4fc2-a396-bf88945def1e"
          ],
          "is_superuser": false,
          "id": "784beba4-8cc8-414f-aab0-e9a29c9b65c2",
          "role_ids": [
            1
          ],
          "display_name": "Fred",
          "is_group": false
        },
        "description": "a fine plan",
        "next_run": "2019-05-05T19:50:08Z",
        "scheduled_time": "2019-05-05T19:50:08Z",
        "schedule_options": {},
        "noop": false,
        "job_options": {
          "noop": false,
          "plan": "canary::random",
        }
      },
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 4,
      "order_by": "next_run",
      "order": "asc"
    }
  }

Error responses

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 400 puppetlabs.orchestrator/validation-error response if there is a problem with a supplied parameter, such as the limit or offset parameters not being formatted as integers.

DELETE /scheduled_jobs/<job-id>

Delete a scheduled job.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include the ID of the scheduled job you want to delete. For example, this request deletes a scheduled job with ID 81:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):8143/orchestrator/v1/scheduled_jobs/81"

curl --insecure --header "$auth_header" DELETE "$uri"

You can use the GET /scheduled_jobs endpoint to find scheduled job IDs.

Response format

Successful deletion returns 204 No Content.

This endpoint's error responses follow the usual format for Orchestrator API error responses. The endpoint returns a 403 puppetlabs.orchestrator/not-permitted response if you don't have permission to delete scheduled jobs.