PingPlotter Cloud API Examples

Here are some examples of how you could use the API:

User Management
Agent Management
Agent Scheduling
Create an Agent from a Ticket
Delete "stale" Agents
Retrieve Trace Data & Statistics

User Management

To automate the user management process, use the /users endpoint.

Here's how to create a user:

curl -X 'POST' \
  'https://yoursubdomain.api.pingplotter.cloud/users' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"' \
  -H 'Content-Type: application/json' \
  -d '{
  "Name": "Testy Tester",
  "EmailAddress": "test@test.test",
  "Roles": [
    "TargetManagement"
  ]
}

Response:

{
  "Id": "u1:FpeVIOlPMulPbX1OyvA",
  "LastLogin": "0001-01-01T00:00:00+00:00",
  "TwoFactorEnabled": false,
  "Name": null,
  "EmailAddress": "test@test.test",
  "Roles": [
    "TargetManagement"
  ]
}

To delete a user, you first need to get the User ID:

curl -X 'GET' \
  'https://yoursubdomain.api.pingplotter.cloud/users' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"'

[
  {
    "Id": "userID",
    "LastLogin": "2023-08-21T18:52:45.6834746+00:00",
    "TwoFactorEnabled": true,
    "Name": "Tony Hawk",
    "EmailAddress": "tony@hawk.com",
    "Roles": null
  },
  {
    "Id": "",
    "LastLogin": "0001-01-01T00:00:00+00:00",
    "TwoFactorEnabled": false,
    "Name": Testy Tester,
    "EmailAddress": "test@test.test",
    "Roles": [
      "TargetManagement"
    ]
  }
]

Then delete the user:

curl -X 'DELETE' \
  'https://yoursubdomain.api.pingplotter.cloud/users/' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"'

Agent Management

To automate management of Agents, for example during employee on/offboarding, use the /agents endpoint.

Here's how to create the Agent:

curl -X 'POST' \
  'https://yoursubdomain.api.pingplotter.cloud/agents' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
   -H 'X-API-KEY: "yourAPIKey"'
  -d '{
  "Name": "string",
  "IsTemplate": true,
  "IsSidekick": true
}'

You'll need the Agent UniqueID before you can delete it:

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

[
  {
    "Name": "raspberrypi",
    "UniqueId": "jksoihf0i2309lkjsdf",
    "IsOnline": true,
    "IsTemplate": false,
    "OpenSessions": 5,
    "TotalSessions": 5,
    "Configured": true,
    "LastMessageTime": "2023-08-14T08:09:12.620545+00:00",
    "MachineID": "",
    "Platform": "Linux",
    "ServiceRunning": true,
    "MachineName": "raspberrypi",
    "MostRecentIPAddress": "",
    "ClientDetails": "",
    "Deleted": false,
    "DeletionDate": null,
    "Notes": null,
    "UserAttributesJson": null,
    "Servers": null,
    "HasSyncedServers": false,
    "CustomFieldsJSON": "{\"Custom1\":\"\",\"Custom2\":\"\",\"MachineName\":\"raspberrypi\",\"Platform\":\"5\",\"Version\":\"5.23.3\",\"VersionGroupName\":\"\",\"Region\":\"Sidekick Cloud\",\"Custom4\":\"Disney\"}",
    "OnWifi": false,
    "OnVPN": false,
    "CurrentNetworkInterface": {
      "IPv6Priority": 0,
      "IPv4Priority": 0,
      "Name": "",
      "RawName": "",
      "Type": "Ethernet",
      "IP": "",
      "Status": "Up",
      "Description": "eth0",
      "Id": "eth0",
      "ConnectedWith": true,
      "SignalPercentage": -1,
      "NoisePercentage": -1,
      "UsedInConfigs": []
    },
    "AutoApprove": null,
    "TemplateUniqueId": null,
    "DownloadUrl": "https://pingplotter.cloud/monitor?configLinkId="
  }
]

Then delete it:

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

Agent Scheduling

If you only care about collecting data or receiving alerts during your Agents' working hours then this is the case for you. You'll end up using the API to start an Agent's trace as they come on shift, and pause the trace as they leave for the day.

You'll need each PingPlotter Cloud Agent's Unique ID to start/stop the traces:

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

[
  {
    "Name": "string",
    "UniqueId": "string",
    "IsOnline": true,
    "IsTemplate": true,
    "OpenSessions": 0,
    "TotalSessions": 0,
    "Configured": true,
    "LastMessageTime": "2023-08-21T17:10:05.112Z",
    "MachineID": "string",
    "Platform": "string",
    "ServiceRunning": true,
    "MachineName": "string",
    "MostRecentIPAddress": "string",
    "ClientDetails": "string",
    "Deleted": true,
    "DeletionDate": "2023-08-21T17:10:05.112Z",
    "Notes": "string",
    "UserAttributesJson": "string",
    "Servers": "string",
    "HasSyncedServers": true,
    "CustomFieldsJSON": "string",
    "OnWifi": true,
    "OnVPN": true,
    "CurrentNetworkInterface": {
      "IPv6Priority": 0,
      "IPv4Priority": 0,
      "Name": "string",
      "RawName": "string",
      "Type": "string",
      "IP": "string",
      "Status": "string",
      "Description": "string",
      "Id": "string",
      "ConnectedWith": true,
      "SignalPercentage": 0,
      "NoisePercentage": 0,
      "UsedInConfigs": [
        "string"
      ]
    },
    "AutoApprove": true,
    "TemplateUniqueId": "string",
    "DownloadUrl": "string"
  }
]

Here's how to start the traces:

curl -X 'PUT' \
  'https://yoursubdomain.api.pingplotter.cloud/agents//sessions?action=Resume' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"'

And pause the traces:

curl -X 'PUT' \
  'https://yoursubdomain.api.pingplotter.cloud/agents//sessions?action=Pause' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"'

Create an Agent from a Ticket

There may be times when the help desk team wants to create an Agent quickly and respond with the Agent download link. This can be done using the /agents endpoint.

curl -X 'POST' \
  'https://yoursubdomain.api.pingplotter.cloud/agents' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"' \
  -H 'Content-Type: application/json' \
  -d '{
  "Name": "",
  "IsTemplate": false,
  "IsSidekick": false
}'

{
  "Name": "New Agent",
  "UniqueId": "8opxhhurw5ewdg17ywr834u8ar",
  "IsOnline": false,
  "IsTemplate": false,
  "OpenSessions": 0,
  "TotalSessions": 0,
  "Configured": false,
  "LastMessageTime": null,
  "MachineID": null,
  "Platform": "NotSpecified",
  "ServiceRunning": false,
  "MachineName": null,
  "MostRecentIPAddress": null,
  "ClientDetails": null,
  "Deleted": false,
  "DeletionDate": null,
  "Notes": null,
  "UserAttributesJson": null,
  "Servers": null,
  "HasSyncedServers": false,
  "CustomFieldsJSON": null,
  "OnWifi": null,
  "OnVPN": null,
  "CurrentNetworkInterface": null,
  "AutoApprove": null,
  "TemplateUniqueId": null,
  "DownloadUrl": "https://pingplotter.cloud/monitor?configLinkId=n9n6tb3bugwruyfr5y6g4qywha"
}

Grab the "DownloadUrl" and make that available for the technician.

Delete "stale" Agents

This workflow is designed to delete Agents that have been in the "pending" status after X amount of time.

First, get the list of all of your Agents:

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

You'll then need to filter your Agents to only those where "Configured" = "False" and "CreationDate" is before your selected deletion data, e.g. 30 days ago.

Once you've filtered the list down to just those select Agents, loop through your list and delete them:

curl -X 'DELETE' \
  'https://yoursubdomain.api.pingplotter.cloud/agents' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: "yourAPIKey"' \
  -H 'Content-Type: application/json' \
  -d '{
  "UniqueId": "AgentUniqueID",
  "ShouldUninstall": false
}'

Retrieving trace data and statistics

Performance Analysis

Filter results to find packet loss events:

GET /session-trace-data/s1:abc123/points?startTime=2025-11-03T10:00:00Z&endTime=2025-11-03T11:00:00Z

Process the response to identify data points where PacketsLost > 0

Batch Statistics Retrieval

Compare performance across multiple sessions:

POST /session-trace-data/stats?startTime=2025-11-03T10:00:00Z&endTime=2025-11-03T11:00:00Z
Body: ["session-1", "session-2", "session-3"]

Process the response to compare average latency, packet loss, and other metrics across sessions.

Monitoring High Latency Events

Identify problematic hops:

GET /session-trace-data/s1:abc123/stats?startTime=2025-11-03T10:00:00Z&endTime=2025-11-03T11:00:00Z

Process the response to find hops where MaximumLatency exceeds your threshold (e.g., 100ms).

PingPlotter Professional

PingPlotter Cloud

PingPlotter Professional

PingPlotter Cloud

Examples

User Management

Agent Management

Agent Scheduling

Create an Agent from a Ticket

Delete "stale" Agents

Retrieving trace data and statistics