API Name: Get Instance Details API
API support for GCP instances is currently undergoing maintenance. We expect full functionality to be restored shortly
Overview
This API returns partition and status information for a single instance identified by its cloud provider, account, and instance ID.
What does this API do?
Lucidity's Get Instance Details API evaluates a specific virtual machine and returns a complete list of its partitions and their statuses. It categorizes all discovered partitions into:
managedResponse: Partitions that are already managed by Lucidity.
unmanagedResponse: Partitions that are pending, ready to onboard, or unsupported.
Common Use Cases
Pre-flight Checks: Verify if specific mount points on an instance are "Ready to Onboard" before submitting a bulk schedule request.
Business Value
Predictability: Prevent failed onboarding jobs by verifying instance and partition eligibility upfront. (Eligibility means Status should be “Ready to Onboard”)
Multi-Cloud Support
The API abstracts cloud complexities by standardizing the request format across providers:
AWS: Requires the AWS Account ID.
Azure: Requires the Subscription ID (and Resource Group, if applicable).
GCP: Requires the GCP Project ID.
Lifecycle (Partition Statuses)
Ready to Onboard: Partition is eligible and waiting to be scheduled.
Onboard Scheduled / Queued for Onboarding : Partition is part of an upcoming onboarding job.
In Progress : Migration is currently in progress.
Finalizing Onboarding : Migration is completed and currently processing in being done
ON_BOARDED (Managed): Partition is successfully managed by Lucidity.
Scheduled for Deboard: A DEBOARD schedule exists for this managed partition.
Failed : During onboarding an error was faced
Not Supported / Not Eligible for Onboarding: Partition cannot be onboarded
1. Fetch Instance Details Purpose: Retrieve the managed and unmanaged partition details for a specific instance.
ENDPOINT: POST /external/client/api/v1/instance/details
Best Practices
Security
Never log or commit API tokens to version control.
Use secure credential storage (vaults, secret managers).
Rotate refresh tokens regularly.
Use HTTPS only.
Performance & Reliability
Pre-validate inputs: Ensure cloudProvider, cloudProviderAccountId, and instanceId are populated correctly before making the request to avoid 400 validation errors. For Azure Case add resource group ID as well.
FAQ
General Questions
Q: Do I need to provide the tenant ID to get instance details? A: No, the backend automatically resolves the tenant based on the cloudProviderAccountId and cloudProvider you provide in the payload.
Q: What is the difference between managedResponse and unmanagedResponse? A: managedResponse lists partitions that are already onboarded and managed by Lucidity. unmanagedResponse lists partitions that are available, unsupported, or currently in the process of being onboarded.
Technical Questions
Q: Why is the endpoint a POST request if it's just fetching details? A: It uses a POST request to securely pass the nested instanceIdentifier JSON payload in the request body, which includes the cloud provider context and account IDs.
Q: What happens if an instance has no managed partitions? A: The managedResponse object will either be omitted or returned with an empty partitionEntries array, depending on the exact instance state.