GetAgentState

Will determine if the product's agent is enabled.

Syntax

Method ID

#define WAAPI_MID_GET_AGENT_STATE 1012

JSON Input Structure

{
  "input": {
    "method": 1012,
    "signature": number,
    "retrieve_agent_info": boolean,
    "assessment_queries": [
      {
        "data_type": string,
        "credentials": {
          "base_url": string,
          "client_id": string,
          "client_secret": string
        }
      },
      ...
    ]
  }
}

Input Properties

Parameter	Type	Description
`retrieve_agent_info`	boolean	(optional) If true, will retrieve the agent's information (eg: agent id). Default value is false.
`assessment_queries`	array<object>	(optional) A list of queries for different types of assessments (e.g., ZTA score, risk score, device posture).
`assessment_queries.data_type`	string	The type of data being queried. This value must be unique within the array. Possible values: 'zta_score', 'last_server_connect_time'.
`assessment_queries.credentials`	object	(optional) Credentials required to authenticate with the API.
`assessment_queries.credentials.base_url`	string	(optional) The base URL of the API endpoint for the specific data type. If the key does not exist then detection will automatically discover the appropriate base URL.
`assessment_queries.credentials.client_id`	string	(optional) A unique identifier for authentication.
`assessment_queries.credentials.client_secret`	string	(optional) A secret key or password for authentication.

JSON Output Structure

{
  "result": {
    "method": 1012,
    "code": number,
    "timing": number,
    "timestamp": string,
    "enabled": boolean,
    "status": string,
    "startup_type": number,
    "agent_id": string,
    "assessment_results": [
      {
        "data_type": string,
        "return_code": number,
        "value": number,
        "message": string
      },
      ...
    ]
  }
}

Output Properties

Property	Type	Description
`result.method`	number	The method ID that generated this result.
`result.code`	number	The result code. See Result Codes.
`result.timing`	number	The measured time for the method call in milliseconds.
`result.timestamp`	string	The timestamp in seconds of when the call was made.
`result.enabled`	boolean	True if the product's agent is enabled.
`result.status`	string	(optional) Status of the agent: 'good', 'poor', 'unmonitored', 'snooze' or 'unknown'. There are also 'idle' and 'pending_restart' statuses, which were designed specifically for Windows Update Agent to describe the status of the system.
`result.startup_type`	number	(optional) (Windows Update Agent only) Returns the startup type of the 'wuauserv' service associated with the Windows Update Agent. The value follows the standard defined in https://learn.microsoft.com/en-us/dotnet/api/system.serviceprocess.servicestartmode. If the retrieved value is invalid, falls outside the defined range, or is otherwise unrecognized, the return value will be -1, indicating an unknown startup type.
`result.agent_id`	string	(optional) The id of the product's agent.
`result.assessment_results`	array<object>	(optional) List of assessment results, each for a different assessment type (e.g., ZTA score, risk score, device status).
`result.assessment_results.data_type`	string	The type of data being queried. This value must be unique within the array Possible values: 'zta_score', 'last_server_connect_time'.
`result.assessment_results.return_code`	number	Result code of the assessment.
`result.assessment_results.value`	number	(optional) Value of the assessment result. • `zta_score`: Return the device score as a number. • `last_server_connect_time`: Return the last server connect time as an epoch number value.
`result.assessment_results.message`	string	(optional) Additional details about the result. This message is only included if the assessment value could not be retrieved.

Result Codes

Code	Name	Description
0	`WAAPI_OK`	The operation completed successfully.

note

Other codes may be returned. See the full Result Codes reference for the complete list.

Remarks

Error Handling

The results of this function are determined by the error code returned by the call. If successful, WAAPI_OK or a special success code will be returned. Always check both the function return value and the result.code field in the output JSON.

Examples

Examples will be added here demonstrating the usage of this method.

Syntax​

Method ID​

JSON Input Structure​

Input Properties​

JSON Output Structure​

Output Properties​

Result Codes​

Remarks​

Error Handling​

Examples​

See Also​