PingPlotter Cloud Manual

Session Trace Data

Overview

Retrieve trace data points and statistics from sessions. These endpoints provide access to raw performance metrics and aggregated statistics for active or completed trace sessions.

Rate Limits

The Session Trace Data API implements rate limiting to ensure fair usage and system stability.

  1. Window Duration: 10 minutes (rolling window) per session. If you request 2 years of data at 10:05 AM, you can request another 1 year at 10:15 AM (10 minutes after your first request).
  2. Maximum Data per Session: 3 years of trace data
  3. Scope: Limits apply per account and session combination

When a rate limit is exceeded, the API returns a 429 Too Many Requests error with details about current usage and when the limit resets.

Best Practices

  • Request data in smaller time ranges when retrieving large datasets
  • Cache responses to avoid redundant API calls
  • Implement exponential backoff when encountering rate limits
  • Use a small time range request first to discover the session's total timeframe (see examples)

GET

GET /session-trace-data/{sessionId}/points

Retrieve aggregated 5-minute bucket trace data points for a specific session within a time range. Important: The timestamp marks the start of the bucket, with data aggregated from that timestamp through timestamp + 5 minutes.

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/session-trace-data/{sessionId}/points?startTime={timestamp}&endTime={timestamp}' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

{
  "EarliestDatapoint": "2025-11-06T22:57:22.416Z",
  "LatestDatapoint": "2025-11-06T22:57:22.416Z",
  "SessionId": "string",
  "AgentUniqueId": "string",
  "AgentName": "string",
  "TargetName": "string",
  "Data": [
    {
      "Timestamp": "2025-11-06T22:57:22.416Z",
      "AverageLatency": 0,
      "MinimumLatency": 0,
      "MaximumLatency": 0,
      "Jitter": 0,
      "PacketsSent": 0,
      "PacketsLost": 0
    }
  ]
}

Query Parameters

Parameter Type Notes
startTime string Required. Start of time range (ISO 8601 format)
endTime string Required. End of time range (ISO 8601 format) 
GET /session-trace-data/{sessionId}/stats

Retrieve aggregated statistics for a specific session.

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/session-trace-data/{sessionId}/stats?startTime={timestamp}&endTime={timestamp}' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'

200 Response

{
  "EarliestDatapoint": "2025-11-06T22:57:22.416Z",
  "LatestDatapoint": "2025-11-06T22:57:22.416Z",
  "SessionId": "string",
  "AgentUniqueId": "string",
  "AgentName": "string",
  "TargetName": "string",
  "Setting": "string",
  "HasData": true,
  "Data": [
    {
      "Hop": 0,
      "Count": 0,
      "Errors": 0,
      "IPAddress": "string",
      "HostName": "string",
      "AverageLatency": 0,
      "MinimumLatency": 0,
      "MaximumLatency": 0,
      "CurrentLatency": 0,
      "Jitter": 0,
      "PacketLossPercentage": 0,
      "Notes": "string"
    }
  ]
}

Query Parameters

Parameter Type Notes
startTime string Required. Start of time range (ISO 8601 format)
endTime string Required. End of time range (ISO 8601 format)

Batch

POST /session-trace-data/points

Retrieve aggregated 5-minute bucket trace data points for a specific session within a time range. Important: The timestamp marks the start of the bucket, with data aggregated from that timestamp through timestamp + 5 minutes.

curl -X 'POST' \
   'https://yoursubdomain.api.pingplotter.cloud/session-trace-data/{sessionId}/points?startTime={timestamp}&endTime={timestamp}' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token' \
   -d '[
      "string"
   ]'

200 Response

[
  {
    "EarliestDatapoint": "2025-11-06T22:57:22.416Z",
    "LatestDatapoint": "2025-11-06T22:57:22.416Z",
    "SessionId": "string",
    "AgentUniqueId": "string",
    "AgentName": "string",
    "TargetName": "string",
    "Data": [
      {
        "Timestamp": "2025-11-06T22:57:22.416Z",
        "AverageLatency": 0,
        "MinimumLatency": 0,
        "MaximumLatency": 0,
        "Jitter": 0,
        "PacketsSent": 0,
        "PacketsLost": 0
      }
    ]
  }
]

Request Body

Key Type Notes
string array Required. List of session id's.

Query Parameters

Parameter Type Notes
startTime string Required. Start of time range (ISO 8601 format)
endTime string Required. End of time range (ISO 8601 format) 
GET /session-trace-data/stats

Retrieve aggregated statistics for multiple sessions.

200 Response

curl -X 'GET' \
   'https://yoursubdomain.api.pingplotter.cloud/session-trace-data/stats?startTime={timestamp}&endTime={timestamp}' \
   -H 'accept: application/json' \
   -H 'X-API-KEY: your_api_token'
   -d '[
      "string"
   ]
[
 {
    "EarliestDatapoint": "2025-11-06T22:57:22.416Z",
    "LatestDatapoint": "2025-11-06T22:57:22.416Z",
    "SessionId": "string",
    "AgentUniqueId": "string",
    "AgentName": "string",
    "TargetName": "string",
    "Setting": "string",
    "HasData": true,
    "Data": [
      {
        "Hop": 0,
        "Count": 0,
        "Errors": 0,
        "IPAddress": "string",
        "HostName": "string",
        "AverageLatency": 0,
        "MinimumLatency": 0,
        "MaximumLatency": 0,
        "CurrentLatency": 0,
        "Jitter": 0,
        "PacketLossPercentage": 0,
        "Notes": "string"
      }
    ]
  }
]

Request Body

Key Type Notes
string array Required. List of session id's.

Query Parameters

Parameter Type Notes
startTime string Required. Start of time range (ISO 8601 format)
endTime string Required. End of time range (ISO 8601 format)