PingPlotter Cloud Manual

Agents

Overview

Agents are deployed to remote devices you wish to monitor and troubleshoot. The Agents endpoints allows you to manage your Agents and sync them with other systems, like Teams, Slack, or your ticketing and Workforce Management systems.

GET

GET /agents

Retrieve all Agents, using query parameters to filter which Agents are returned.

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/agents?includeTemplates=false&includeDeleted=false' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

[
    {
        "Name": "string",
        "UniqueId": "string",
        "IsOnline": true,
        "IsTemplate": true,
        "IsBorrowed": true,
        "OpenSessions": 0,
        "TotalSessions": 0,
        "Configured": true,
        "LastMessageTime": "2025-11-05T22:45:28.094Z",
        "CreationDate": "2025-11-05T22:45:28.094Z",
        "MachineID": "string",
        "Platform": "string",
        "ServiceRunning": true,
        "MachineName": "string",
        "MostRecentIPAddress": "string",
        "ClientDetails": "string",
        "Deleted": true,
        "DeletionDate": "2025-11-05T22:45:28.094Z",
        "Notes": "string",
        "UserAttributesJson": "string",
        "Servers": "string",
        "HasSyncedServers": true,
        "CustomFields": [
            {
                "Name": "string",
                "Value": "string"
            }
        ],
        "OnWifi": true,
        "OnVPN": true,
        "CurrentNetworkInterface": {
            "IPv6Priority": 0,
            "IPv4Priority": 0,
            "Name": "string",
            "RawName": "string",
            "Type": "string",
            "GatewayIP": "string",
            "AdapterIP": "string",
            "Status": "string",
            "Description": "string",
            "Id": "string",
            "ConnectedWith": true,
            "SignalPercentage": 0,
            "NoisePercentage": 0,
            "UsedInConfigs": [
                "string"
            ]
        },
        "ConnectionType": "string",
        "AutoApprove": true,
        "TemplateUniqueId": "string",
        "DownloadUrl": "string",
        "ExpectedQuality": {
            "Id": "string",
            "Name": "string"
        }
    }
]

Query Parameters

Parameter Type Notes
includeTemplates boolean Default: false. If true, include Agent Templates
includeDeleted boolean Default: false. If true, include deleted Agents. 
GET /agents/{uniqueId}

Retrieve a single Agent by Unique Id.

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/{UniqueId}' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

{
    "Name": "string",
    "UniqueId": "string",
    "IsOnline": true,
    "IsTemplate": true,
    "IsBorrowed": true,
    "OpenSessions": 0,
    "TotalSessions": 0,
    "Configured": true,
    "LastMessageTime": "2025-11-05T23:27:49.803Z",
    "CreationDate": "2025-11-05T23:27:49.803Z",
    "MachineID": "string",
    "Platform": "string",
    "ServiceRunning": true,
    "MachineName": "string",
    "MostRecentIPAddress": "string",
    "ClientDetails": "string",
    "Deleted": true,
    "DeletionDate": "2025-11-05T23:27:49.803Z",
    "Notes": "string",
    "UserAttributesJson": "string",
    "Servers": "string",
    "HasSyncedServers": true,
    "CustomFields": [
        {
            "Name": "string",
            "Value": "string"
        }
    ],
    "OnWifi": true,
    "OnVPN": true,
    "CurrentNetworkInterface": {
        "IPv6Priority": 0,
        "IPv4Priority": 0,
        "Name": "string",
        "RawName": "string",
        "Type": "string",
        "GatewayIP": "string",
        "AdapterIP": "string",
        "Status": "string",
        "Description": "string",
        "Id": "string",
        "ConnectedWith": true,
        "SignalPercentage": 0,
        "NoisePercentage": 0,
        "UsedInConfigs": [
            "string"
        ]
    },
    "ConnectionType": "string",
    "AutoApprove": true,
    "TemplateUniqueId": "string",
    "DownloadUrl": "string",
    "ExpectedQuality": {
        "Id": "string",
        "Name": "string"
    }
}
GET /agents/customfields

Retrieve all available Agent Custom Fields.

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/customfields' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

[
    {
        "Name": "string"
    }
]

POST

POST /agents

Create a new Agent or Agent Template.

curl -X 'POST' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/customfields' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '{
      "Name": "My New Agent",
      "Targets": [
         {
            "Target": "pingplotter.cloud PPC",
            "ConfigurationId": "your_configuration_id",
            "TraceIntervalInMs": 2500
         }
      ],
      "IsTemplate": false
}'

200 Response

{
  "Name": "string",
  "UniqueId": "string",
  "IsOnline": boolean,
  "IsTemplate": boolean,
  "IsBorrowed": boolean,
  "OpenSessions": int,
  "TotalSessions": int,
  "Configured": boolean,
  "Platform": "NotSpecified",
  "ServiceRunning": boolean,
  "Deleted": boolean,
  "HasSyncedServers": boolean,
  "DownloadUrl": "string"
}

Request Body

Key Type Notes
Name string Required. Name of the Agent
Targets target array List of Targets to be activated when the Agent is first installed: {"Target": "string", "ConfigurationId": "your_configuration_id", "TraceIntervalInMs": 2500}
Target string IP Address, Hostname, or URL of the Target. Tip: Create an alias for the target by separating it with a space, e.g. 192.168.0.1 Router
ConfigurationId string Id of the desired configuration. Defaults to account default (typically ICMP). Use the Settings API to get a full list of these Id's.
TraceIntervalInMs string Time between trace samples. Default: 2500. 
POST /agents/{uniqueId}/status

Retrieve the current status of an Agent and its Targets.

curl -X 'POST' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/{uniqueId}/status' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '{
     "TargetName": "string",
     "TargetIp": "string",
     "QualityDefinitionIds": [
       "string"
     ]
   }'

200 Response

{
    "AgentUniqueId": "string",
    "IsOnline": true,
    "OnWifi": true,
    "OnVPN": true,
    "LastMessageTime": "2025-11-06T15:53:54.339Z",
    "LastMessageTimestampInMs": 0,
    "TargetQuality": [
        {
            "QualityDefinitionId": "string",
            "QualityValue": "string",
            "MeasuredAt": "2025-11-06T15:53:54.339Z",
            "MeasuredAtTimestampInMs": 0,
            "QualityScore": 0,
            "SessionId": "string",
            "Description": "string",
            "IpAddress": "string"
        }
    ]
}

Request Body

Key Type Notes
TargetName string Name of the Target, e.g. pingplotter.com
TargetIp string IP Address of the Target, e.g. 216.92.151.75
QualityDefinitionIds string array List of Quality Definition Id's 
POST /agents/{uniqueId}/forcereconnect

Forcibly disconnects an Agent's connection to PingPlotter Cloud and establishes a new one.

curl -X 'POST' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/{uniqueId}/forcereconnect' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

true

PUT

PUT /agents/{uniqueId}

Update an Agent's name

curl -X 'PUT' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/{uniqueId}' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '{
     "Name": "string"
   }'

200 Response

true
PUT /agents/{uniqueId}/session

Update the status of a single session (Target) on an Agent.

curl -X 'PUT' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/{uniqueId}/session' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '{
     "SessionId": "string",
     "Action": "string"
   }'

200 Response

true

Request Body

Key Type Notes
SessionId string Required. Id of the session
Action string Required. Action to take on the session: pause/resume. 
PUT /agents/{uniqueId}/sessions

Update the status of all sessions (Targets) on an Agent.

curl -X 'PUT' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/{uniqueId}/sessions?action=0' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

true

Query Parameters

Parameter Type Notes
Action integer Required. Action to take on the sessions. 0 = pause, 1 = resume

DELETE

DELETE /agents

Delete an Agent, with the option to uninstall (must be online to uninstall).

curl -X 'DELETE' \
   'https://yoursubdomain.api.pingplotter.cloud/agents' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '{
     "UniqueId": "string",
     "ShouldUninstall": true
   }'

200 Response

true

Request Body

Key Type Notes
UniqueId string Required. Unique Id of the Agent to delete
ShouldUninstall boolean Uninstall the Agent from the remote device. Agent must be currently online to uninstall. Default: false.

Batch

POST /agents/status

Retrieve the current status of multiple Agents and their Targets.

curl -X 'POST' \
   'https://yoursubdomain.api.pingplotter.cloud/agents/status' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '{
     "TargetName": "string",
     "TargetIp": "string",
     "QualityDefinitionIds": [
       "string"
     ],
     "AgentUniqueIds": [
       "string"
     ]
   }'

200 Response

[
    {
        "AgentUniqueId": "string",
        "IsOnline": true,
        "OnWifi": true,
        "OnVPN": true,
        "LastMessageTime": "2025-11-06T17:39:55.950Z",
        "LastMessageTimestampInMs": 0,
        "TargetQuality": [
            {
               "QualityDefinitionId": "string",
               "QualityValue": "string",
               "MeasuredAt": "2025-11-06T17:39:55.950Z",
               "MeasuredAtTimestampInMs": 0,
               "QualityScore": 0,
               "SessionId": "string",
               "Description": "string",
               "IpAddress": "string"
            }
        ]
    }
]

Request Body

Key Type Notes
TargetName string Name of the Target, e.g. pingplotter.com
TargetIp string IP Address of the Target, e.g. 216.92.151.75
QualityDefinitionIds string array List of Quality Definition Id's. Use the Settings API to get a full list of these Id's.
AgentUniqueIds string array Required. List of Agent Id's