API Name: Agent Install Status API
Track and monitor the progress of your Lucidity agent deployments.
API support for GCP instances is currently undergoing maintenance. We expect full functionality to be restored shortly
Overview
This API is used to fetch the status of a bulk agent installation job. The id used in this API is returned in the Agent Install API response and represents the unique identifier for that specific installation job.
What does this API do?
Lucidity's Agent Install Status API allows you to programmatically query the real-time execution state of your agent installation requests. By providing the job ID as a query parameter, you can determine exactly where the installation stands in its lifecycle, from queued to completed.
This API is used to fetch the status of a bulk agent installation job. The id used in this API is returned in the Agent Install API response and represents the unique identifier for that specific installation job.
Common Use Cases
Asynchronous Monitoring: Poll the API to check when an installation job finishes so subsequent automation steps can proceed.
Reporting & Alerting: Build custom dashboards or trigger alerts based on the success or failure of bulk onboarding efforts.
Troubleshooting: Quickly identify instances where the installation status is marked as FAILED or CANCELLED to initiate remediation.
Business Value
Visibility: Gain real-time insights into your fleet-wide agent deployment progress.
Automation: Enable fully automated CI/CD pipelines that can wait for confirmation of agent installation before continuing.
Reliability: Ensure all targeted instances are successfully running the agent by programmatically verifying their final status.
Multi-Cloud Support
The Lucidity API provides a unified interface across AWS, Azure, and GCP. The status tracking relies on the unique job id generated during the install request, seamlessly abstracting the underlying cloud provider's specifics.
Lifecycle
QUEUED: Job has been queued for processing.
PREPARING: System is preparing the installation environment.
PROCESSING: Agent installation is currently in progress.
COMPLETED: Agent installation completed successfully.
FAILED: Agent installation failed.
CANCELLED: Job was cancelled.
UNKNOWN: Job status could not be determined.
1. Check Agent Install Status
Purpose: Retrieve the current execution status of a previously scheduled installation job.
ENDPOINT: GET /external/client/api/v1/agent/install/status?id={the id that you received in the Create Agent Installation Request}
Best Practices
Security
Never log or commit API tokens to version control.
Use secure credential storage (vaults, secret managers)
Rotate access tokens regularly, as they are short-lived.
Use HTTPS only for all API communications.
Performance & Reliability
Implement exponential backoff: When polling for status, avoid overwhelming the endpoint; use escalating delays between requests.
Handle terminal states:Ensure your automated scripts properly break out of polling loops once a terminal status (COMPLETED, FAILED, CANCELLED) is reached.
Cost Optimization
Stop polling upon completion: Terminate your polling loops immediately once a final state is reached to save compute and network resources on your end.
Operational Excellence
Log terminal states: Keep a historical record of job IDs that end in FAILED or UNKNOWN for later audit and troubleshooting.
Map IDs accurately: Ensure the id from the initial POST request is passed exactly as received (it is a Long data type) to avoid 404 or mismatch errors.
FAQ
General Questions
Q: Where do I find the id required for this API?
A: The id is returned in the success response array of the Agent Install API (POST request) when you first initiate the installation.Q: How often should I call this API to check the status?
A: We recommend polling every 10-15 seconds with an exponential backoff strategy rather than sending continuous, rapid-fire requests.
Technical Questions
Q: What HTTP method and parameter format does this endpoint use?
A: It uses a GET request, with the job identifier passed as a URL query parameter (e.g., ?id=2).Q: What does an UNKNOWN status mean?
A: This indicates a communication gap or internal synchronization issue where the system temporarily cannot determine the current state. Retrying the status check after a few seconds will typically resolve it.