PingPlotter Cloud Manual

Sessions

Overview

Sessions, or Targets, are the network traces running on the remote device to gather latency and packet loss statistics for the specificed IP address, hostname, or URL.

GET

GET /sessions

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

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/sessions?agentUniqueId="{uniqueId}"&targetName="pingplotter.cloud"' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

[
   {
      "AgentUniqueId": "string",
      "SessionId": "string",
      "Description": "string",
      "IpAddress": "string",
      "Status": "string",
      "ExpectedQuality": {
         "Id": "string",
         "Name": "string"
      }
   }
]

Query Parameters

Parameter Type Notes
agentUniqueId string Unique Id of an Agent.
targetName string Name of the desired Target, e.g. pingplotter.cloud
targetIp string IP Address of the desired Target, e.g. 1.1.1.1 
GET /sessions/{sessionId}

Retrieve a single Session by Session Id.

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

200 Response

{
   "AgentUniqueId": "string",
   "SessionId": "string",
   "Description": "string",
   "IpAddress": "string",
   "Status": "string",
   "ExpectedQuality": {
      "Id": "string",
      "Name": "string"
   }
}
GET /sessions/{sessionId}/status

Retrieve a single Session's quality score status.

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

200 Response

{
   "SessionId": "string",
   "Description": "string",
   "IpAddress": "string",
   "TargetQuality": [
      {
         "QualityDefinitionId": "string",
         "QualityValue": "string",
         "MeasuredAt": "2025-11-06T21:18:21.446Z",
         "MeasuredAtTimestampInMs": 0,
         "QualityScore": 0
      }
   ]
}

POST

POST /sessions

Create new session(s). Accepts an array of targets.

curl -X 'POST' \
   'https://yoursubdomain.api.pingplotter.cloud/sessions' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '[
      {
        "Target": "string",
        "ConfigurationId": "string",
        "TraceIntervalInMs": 0,
        "AgentUniqueId": "string"
      }
   ]'

200 Response

true

Request Body

Key Type Notes
Target string Required. 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 in milliseconds. Default: 2500.
AgentUniqueId string Required. UniqueId of the Agent that will run the session.

PUT

PUT /sessions

Pause or resume a session

curl -X 'PUT' \
   'https://yoursubdomain.api.pingplotter.cloud/sessions' \
   -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. Options: resume or pause. 
PUT /sessions/{sessionId}/close

Stop tracing and close a session. (Request Body is empty)

curl -X 'PUT' \
   'https://yoursubdomain.api.pingplotter.cloud/sessions/{sessionId}/close' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

true
PUT /sessions/{agentUniqueId}

Pause or resume all sessions for an Agent.

curl -X 'PUT' \
   'https://yoursubdomain.api.pingplotter.cloud/sessions/{agentUniqueId}?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

Batch

POST /sessions/status

Retrieve quality score status for multiple Sessions.

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

200 Response

[
   {
      "SessionId": "string",
      "Description": "string",
      "IpAddress": "string",
      "TargetQuality": [
         {
            "QualityDefinitionId": "string",
            "QualityValue": "string",
            "MeasuredAt": "2025-11-06T21:18:21.446Z",
            "MeasuredAtTimestampInMs": 0,
            "QualityScore": 0
         }
      ]
   }
]

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
SessionsIds string array Required.List of Session Id's