Skip to main content

Get Clore Agent Status

Endpoint Description​

GET /clore/v1/machines/agents/{deployment_id}

This endpoint retrieves the status of the Clore Agent on a specified machine. It requires authentication and specific user roles to access. The request must include the deployment ID to identify the running instance of the Clore Agent.

Request Parameters​

The request parameters for getting the Clore Agent status must be specified in the URL path.

Parameters​

  • deployment_id: string
    • The unique identifier for the deployment of the Clore Agent whose status is being requested.

Example Request​

GET /clore/v1/machines/agents/a1b2c3d4-5678-90ef-ghij-klmnopqrstuv

Success Response​

Status Code: 200 OK

Response Body Description​

The response body contains information about the status of the Clore Agent deployment.

Fields​

  • deployment_id: string
    • The unique identifier for the deployment.
  • machine_id: string
    • The unique identifier for the machine on which the Clore Agent is running.
  • status: enum
    • The current status of the Clore Agent.
    • Possible values:
      • STATUS_UNSPECIFIED: The status is unspecified.
      • STATUS_PENDING: The agent has been scheduled and is waiting to be processed.
      • STATUS_STOPPING: The agent is in the process of stopping.
      • STATUS_STOPPED: The agent has been stopped.
      • STATUS_FAILED: The agent operation encountered an error and failed.
      • STATUS_RUNNING: The agent is running.
  • fail_reason: string
    • The reason for failure, if any.
  • metadata: map<string, string>
    • Additional metadata about the deployment, represented as key-value pairs.

Example Response Body​

{
  "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
  "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
  "status": "STATUS_RUNNING",
  "fail_reason": "",
  "metadata": {
    "example_key": "example_value"
  }
}

HTTP Status Codes​

The "Get Clore Agent Status" endpoint may return the following HTTP status codes based on the outcome of the request:

  • 200 OK: The request was successful, and the response body contains the status of the Clore Agent.
  • 400 Bad Request: The server could not understand the request due to invalid syntax. This status is typically returned if the required parameter is missing or incorrectly formatted.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource. This status indicates that the client must authenticate themselves to get the requested response.
  • 403 Forbidden: The server understood the request but refuses to authorize it. This typically means the requester doesn't have the required roles to access the resource.
  • 404 Not Found: The requested resource could not be found. This status may be returned if the deployment ID is incorrect.
  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error message when no specific message is suitable.

Example cURL Request​

curl -X GET "https://api.hiveon.ai/clore/v1/machines/agents/a1b2c3d4-5678-90ef-ghij-klmnopqrstuv" \
     -H "Accept: application/json"

This cURL command retrieves the status of the Clore Agent on a specified machine, using the provided deployment ID.