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
https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs?limit=20&type=task
Copied!
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
.
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.
false for task and
plan jobs. |
job_options |
A JSON object containing options supplied to the job. |
pagination
object uses these keys:-
total
: The total number of job records in the collection, regardless oflimit
andoffset
. -
limit
,offset
,order_by
,order
, andtype
: 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.
{
"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
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.