Poll a long-running action and respond when input is required

Some BinaryLane API operations return an action that continues processing in the background. You can check the action until it completes, fails, or asks you for a decision.

This guide shows the same workflow with the bl command line client and the BinaryLane API.

TABLE OF CONTENTS

• Before you begin
• Get the action ID
  • If an operation is already waiting
  • When starting a new operation
• Check the action
• Check whether the action needs input
• Respond to the interaction
• Confirm the final result
• Troubleshooting
  • The action remains in progress
  • The proceed request fails
  • The interaction type is unfamiliar
• Applies to

Before you begin

You need:

• a BinaryLane API token
• bl 0.21.0 if you want to use the command line examples

For token setup, see Getting Started with BinaryLane API. For bl, follow the CLI configuration instructions. The curl examples use Bash syntax and the BINARYLANE_API_TOKEN environment variable described in the API guide. The examples use ${BINARYLANE_API_TOKEN} for your token, ${server_id} for a server ID, and ${action_id} for an action ID.

Get the action ID

If an operation is already waiting

Open a second terminal if the original bl command is still waiting. List its actions with enough detail to identify the server and operation:

bl action list --format "id,type,resource_type,resource_id,started_at,status"

Match resource_type and resource_id to the affected server, then check the operation type and start time. Record the matching action's id. Do not choose an action just because it is the newest one. If a resource is not listed or the match is unclear, inspect the action before proceeding.

This command lists all pages of the account's action history. The selected columns make the output easier to scan; they do not filter which actions are returned.

When starting a new operation

Record the action ID from the original API response when it contains one. With bl, commands that support --async return without waiting for the action to finish. bl server create --async and bl load-balancer create --async display an action_id row in their default output.

Other action commands produce no output by default with --async. Choose --output table to see the returned action. For example, this command shuts down the selected server and displays the shutdown action:

bl server action shutdown ${server_id} --async --output table

Record its id. Do not start another operation just to find the ID of one that is already running; use the action list above.

Check the action

With bl:

bl action get ${action_id} --output json

With the API:

curl --request GET \
  "https://api.binarylane.com.au/v2/actions/${action_id}" \
  --header "Authorization: Bearer ${BINARYLANE_API_TOKEN}"

Check these fields in the returned action object:

If the action is still in progress and does not require input, wait before checking it again. The API does not prescribe a polling interval. For a simple script, a short delay such as five seconds is a reasonable starting point. Also set an overall timeout appropriate to the operation so a script cannot wait forever.

Treat any non-successful HTTP response as an error. Record the HTTP status and response for troubleshooting instead of interpreting it as an action state.

Check whether the action needs input

When user_interaction_required is not null, inspect its interaction_type before responding.

The following is an illustrative, shortened response:

{
  "action": {
    "id": 123456,
    "status": "in-progress",
    "completed_at": null,
    "user_interaction_required": {
      "interaction_type": "continue-after-ping-failure"
    }
  }
}

BinaryLane API 0.40.0 documents these interaction types:

Do not automatically approve an interaction just because the field is set. If your automation receives an interaction type it does not recognise, stop and inspect it. Do not call the proceed endpoint until you understand the decision being requested.

Respond to the interaction

The proceed value answers the question represented by the interaction type:

• true answers yes
• false answers no

Review the affected server and interaction type before choosing. An unclean power-off can lose unsaved data; only permit it when that risk is acceptable for the workload.

To answer yes with bl:

bl action proceed ${action_id} --proceed

To answer no:

bl action proceed ${action_id} --no-proceed

The equivalent API request for yes is:

curl --request POST \
  "https://api.binarylane.com.au/v2/actions/${action_id}/proceed" \
  --header "Authorization: Bearer ${BINARYLANE_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"proceed": true}'

Use {"proceed": false} to answer no.

A successful proceed request returns 204 No Content. This confirms that the response was accepted. It does not confirm that the action has completed.

Confirm the final result

After responding, check the action again:

bl action get ${action_id} --output json

Continue until status is either:

• completed: the action finished successfully
• errored: BinaryLane encountered an error while processing the action

If your overall timeout expires, stop polling and preserve the latest action response. Check the action again later or contact BinaryLane support with the action ID and the latest status.

Troubleshooting

The action remains in progress

Check user_interaction_required. The bl client's built-in wait loop checks for completion, but it does not answer a required interaction for you.

If you started the action with bl without --async, the client keeps waiting while the action is paused for your decision. Its progress display does not tell you that input is required, and the client does not apply a timeout.

Open a second shell and use the bl action list command above to find the current action. Then inspect it with bl action get. You can interrupt the waiting command with Ctrl+C. To avoid this situation, start supported operations with --async, choose --output table when the command would otherwise produce no output, and poll the action yourself.

If no interaction is required, allow more time or stop at the timeout you set in your own polling script. The API does not document a universal completion time for actions.

The proceed request fails

Confirm that:

• the action ID is correct
• the action currently has user_interaction_required set
• the request body contains a boolean proceed value
• the API token is valid

Do not repeatedly send the proceed request without first fetching the current action again. The API specification does not define duplicate-request or idempotency behaviour for this endpoint.

The interaction type is unfamiliar

Do not guess what true means. Preserve the action ID and interaction value, then contact BinaryLane support before responding.

Applies to

• BinaryLane API 0.40.0
• binarylane-cli 0.21.0