GET /plan_jobs/<job-id>/events

Retrieve a list of events that occurred during a specific plan job.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include an integer job ID identifying a specific plan job. Plan job IDs are returned in responses from plan-related Command endpoints and the GET /plan_jobs endpoint.

You can use the optional start parameter to start the list of events from a specific event ID number.

For example, this request queries events associated with the 352 plan job, starting with event number 1272:

GET https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/events?start=1272

Response format

A successful response is a JSON object containing a next-events object and an items array.

The next-events object contains two subkeys:

  • id: The URI supplied in the request.
  • event: The ID of the first event returned or the start parameter, if supplied in the request.

The items array uses these keys to detail the plan job's events:

Key Definition
id An individual event's ID
type Each event has one event type, determined by the event's status or circumstances that cause it to occur:
  • task_start: A task run started.
  • script_start: A script run starts as part of a plan.
  • command_start: A command run starts as part of a plan.
  • upload_start: A file upload starts as part of a plan.
  • wait_start: A wait_until_available() call starts as part of a plan.
  • out_message: As part of a plan, out::message is called.
  • apply_start: A puppet apply run started as part of a plan.
  • apply_prep_start: An apply_prep run starts as part of a plan.
  • plan_finished: The plan job successfully finished.
  • plan_failed: The plan job failed.

A plan containing the run_plan() function completes the secondary plan during the primary plan job. Such subplans do not have their own plan jobs – They are included with, and completed as part of, the original job. These event types indicate when a subplan started or finished:

  • plan_start: The run_plan() function started a plan within the current plan job.
  • plan_end: The subplan, triggered by the run_plan() function, finished. This event type is specific to subplans and different from plan_finished.
timestamp The time the event occurred or was created.
details A JSON object containing information about the event. Specific contents depends on the event type:
  • For any *_start events (except plan_start), details include the job-id of the associated action or task.
  • For plan_finished and plan_failed events, details include the plan-id and result.
  • For out_message events, details include the message contents, truncated to 1,024 bytes. You can use the GET /plan_jobs/<job-id>/event/<event-id> endpoint to get the full message content.
  • For plan_start events, details include the plan, which identifies the subplan that ran within the original plan.
  • For plan_end events, details include the plan (which is the subplan that ran within the original plan) and the duration (which is how long the subplan ran).

Here is an example response body:

{
  "next-events" : {
    "id" : "https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/events?start=1272",
    "event": "1272"
  },
  "items" : [ {
    "id" : "1273",
    "type" : "task_start",
    "timestamp" : "2016-05-05T19:50:08Z",
    "details" : {
      "job-id" : "8765"
    }
  },
  {
    "id" : "1274",
    "type" : "plan_finished",
    "timestamp" : "2016-05-05T19:50:14Z",
    "details" : {
      "plan-id" : "1234",
      "result" : {
        "Plan output"
      },
    },
  }]
}

Error responses

If there is an error, Orchestrator API error responses provide error information in the kind key:

Response code Key Description
400 puppetlabs.orchestrator/validation-error The plan job ID or the start parameter in the request are not supplied as integers.
404 puppetlabs.orchestrator/unknown-job No plan job exists that matches the specified plan job ID.