Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Orchestrating Puppet runs, tasks, and plans Grey arrow pointing right Orchestrator API v1 Grey arrow pointing right Scheduled jobs endpoints Grey arrow pointing right

Scheduled jobs endpoints

Sections

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=taskCopied!
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"
    }
  }Copied!

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"Copied!
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.