Scheduled jobs endpoints

Use the /scheduled_jobs endpoint to gather information about orchestrator jobs scheduled to run.

GET /scheduled_jobs

List scheduled jobs in ascending order.

Parameters

The request accepts the following query parameters:

Parameter Definition
limit Return only the most recent n number of jobs.

offset

Return results offset n records into the result set.
order_by One of next_run (default), scheduled_time, name.
order asc (default) or desc
type The type of job. Matches the command that created the job, one of: deploy, task, or plan.

For example:

https://orchestrator.example.com:8143/orchestrator/v1/scheduled_jobs?limit=20&offset=20

Response format

The response is a JSON object that contains a list of the known jobs and information about the pagination.

Key Definition
items Contains an array of all the scheduled jobs.
id An absolute URL to the given job.
name The ID of the scheduled job
type The type of scheduled job (currently only task)
task The name of the task associated with the scheduled task job
plan The name of the plan associated with the scheduled plan job
scope The specification of the targets for the task.
environment The environment that the job operates in.
owner The specification for the user that requested the job.
email String
login String
display_name String
is_revoked Boolean
last_login ISO-8601 timestamp
is_remote A boolean for the type of user
is_group A boolean for the type of user
is_superuser A boolean for the type of user
role_ids Array
inherited_role_ids Array
group_ids Array
description A user-provided description of the job.
next_run An ISO-8601 timestamp for the next run of a scheduled job.
scheduled_time An ISO8601 timestamp for when the scheduled job runs.
schedule_options Object
interval Object
units Enum [seconds]
value Positive integer
noop Boolean. Is true if the job runs in no-operation mode, false otherwise. Always false for task or plan jobs.
job_options Object for the options supplied for the job.
pagination Contains the information about the limit, offset and total number of items.
limit A restricted number of items for the request to return.
offset A number offset from the start of the collection (zero based).
total The total number of items in the collection, ignoring limit and offset.
order_by The sort field, one of next_run (default), scheduled_time, or name.
order asc or desc
type The type of job filtered on, if any. One of deploy, task, or plan.

For example:

{
    "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

See Orchestrator API error responses for the format of error responses. For this endpoint, the kind key of the error displays the conflict.

Key Definition
puppetlabs.orchestrator/validation-error If the limit or offset parameter is not an integer, the server returns a 400 response.

DELETE /scheduled_jobs/:job-id

Delete a scheduled job.

  • Response 204

  • Response 403

    • Body 
      {
  "kind": "puppetlabs.orchestrator/not-permitted",
  "msg": "Not authorized to delete job {id}"
}