Help Center/ Cloud Backup and Recovery/ API Reference/ CBR APIs/ Protection/ Querying the Agent Status
Updated on 2026-08-10 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying the Agent Status

Function

This API is used to check the application-consistent Agent status.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

POST /v3/{project_id}/agent/check

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

agent_status

Yes

Array of ProtectableAgentStatusResource objects

Definition

Query parameter list.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 3 ProtectableAgentStatusResource

Parameter

Mandatory

Type

Description

resource_id

Yes

String

Definition

ID of the resource to be checked. The value is in UUID format. You can query the resource ID based on the type of the resource to be backed up.

Constraints

The resource type must be the same as that specified by resource_type.

Range

N/A

Default Value

N/A

resource_name

No

String

Definition

Name of the resource to be checked.

Constraints

The value must correspond to the ID of the resource to be checked.

Range

N/A

Default Value

N/A

resource_type

Yes

String

Definition

Type of the resource to be checked.

Constraints

The value must correspond to the ID of the resource to be checked.

Range

OS::Nova::Server: The resource is an ECS.

OS::Ironic::BareMetalServer: The resource is a BMS.

Default Value

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

agent_status

Array of ProtectableAgentStatus objects

Status list
Table 5 ProtectableAgentStatus

Parameter

Type

Description

code

Integer

Definition

Error code indicating that the agent cannot be connected. For details, see Error Codes.

Range

N/A

installed

Boolean

Definition

Whether the agent is installed.

Range

  • true: installed

  • false: not installed

is_old

Boolean

Definition

Whether the installed agent is of an earlier version.

Range

  • true: earlier version

  • false: not an earlier version

message

String

Definition

Error information indicating that the agent cannot be connected. The possible cause is that the corresponding agent is not found. For details, see Error Codes.

Range

N/A

resource_id

String

Definition

Resource ID, in UUID format.

Range

N/A

version

String

Definition

Agent version.

Range

N/A

Example Requests

Query the agent status of a cloud server.

POST https://{endpoint}/v3/f841e01fd2b14e7fa41b6ae7aa6b0594/agent/check

{
  "agent_status" : [ {
    "resource_id" : "6c0e29fc-5eaa-4f76-af9e-cc79895f70d7",
    "resource_name" : "ecs-8f7b",
    "resource_type" : "OS::Nova::Server"
  } ]
}

Example Responses

Status code: 200

OK

{
  "agent_status" : [ {
    "resource_id" : "6c0e29fc-5eaa-4f76-af9e-cc79895f70d7",
    "installed" : false
  } ]
}

Status Codes

Status Code

Description

200

OK

Error Codes

See Error Codes.

Parent topic: Protection