Start and monitor workflows with the Pantheon Public API
Start and monitor workflows
Learn how to start a workflow, such as creating a multidev environment, and poll for its completion using the Pantheon Public API.
Actions that change your site, such as creating an environment, deploying code, or cloning a database, run as workflows. When you start one of these actions, the API returns a workflow ID immediately while the work continues in the background. To find out when the action is done, poll the workflow's status until it finishes.
This page walks through creating a multidev environment and waiting for it to be ready. The same pattern applies to other workflow-based actions.
The examples on this page assume your Personal Access Token is stored in the PANTHEON_TOKEN environment variable. See Authenticate with the Public API.
Start a workflow
Create a multidev environment by sending a POST request to the site's multidevs endpoint, replacing <site_uuid>. The request body contains:
siteId: the site's UUID.name: the name of the new multidev environment. See What are the naming conventions for branches? for allowed names.cloneFromEnv: the environment to copy the database and files from, such asdev.annotation: a short description of why the workflow was run, recorded with the workflow.
The response is an object that includes the workflow's id and a status object describing the workflow. At creation, the status object's own status field is null, so use the id to poll for the current status. Save the id to check on the workflow's progress. To capture it in a variable with jq:
Check a workflow's status
Request the workflow by its ID:
The status field of the response summarizes the workflow's progress:
| Status | Meaning |
|---|---|
NOT_STARTED | The workflow is queued and hasn't started yet. |
IN_PROGRESS | The workflow is running. |
SUCCESS | The workflow completed successfully. |
FAILED | The workflow failed. See the reason field. |
CANCELED | The workflow was stopped before it ran, for example because of invalid input. See the reason field. |
The response also includes activeDescription, a human-readable description of the current step, and progress, an estimate of the workflow's progress from 0 to 100. The reason field is an array of strings. It is empty unless the workflow failed or was canceled. The activeDescription of a failed workflow can still describe the step it was attempting, so check status rather than relying on activeDescription alone.
Poll for completion
To wait for a workflow to finish, check its status in a loop until it reaches SUCCESS, FAILED, or CANCELED. Wait a few seconds between requests. Creating a multidev environment can take several minutes:
Note: It's possible for polling requests to return an error in the case of a bad response even while the workflow is still running. When writing your polling function, ensure that the loop continues on errors rather than stopping the loop.
When the loop ends, check STATUS. If the workflow failed or was canceled, the reason field explains why:
Once the multidev workflow succeeds, the new environment appears in the site's multidevEnvironmentNames when you get site information.
