GET /plan_jobs/<job-id>/event/<event-id>

Retrieve the details of a specific event for a specific plan job.

Request format

When Forming orchestrator API requests to this endpoint, the URI path must include an integer plan job ID and an integer event ID. You can get plan job IDs from plan-related Command endpoints and the GET /plan_jobs endpoint. You can get event IDs from the GET /plan_jobs/<job-id>/events endpoint.

For example, this request queries event number 1272 for plan job number 352:

GET https://orchestrator.example.com:8143/orchestrator/v1/plan_jobs/352/event/1272
The URI path uses the singular event, and not events, like the GET /plan_jobs/<job-id>/events endpoint.

Response format

A successful response is a JSON object that uses these keys to provide the event details:

Key Definition
id The event's ID.
type The event's 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 complete message contents.
  • For plan_start events, details include the plan, which identifies the subplan that ran within the original plan.
  • For plan_end events, detail 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 of a response body:

{    
    "id": "1265",
    "type": "out_message",
    "timestamp": "2016-05-05T19:50:06Z",
    "details": {
        "message": "this is an output message"
    }
}

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 event ID in the request are not supplied as integers.
404 puppetlabs.orchestrator/unknown-job No plan job exists that matches the specified plan job ID.
404 puppetlabs.orchestrator/mismatched-job-event-id The specified event ID does not match any event ID associated with the specified plan job ID.