Skip to main content

​
POST /api/v1//ping/

Initiates an asynchronous network diagnostic task (ICMP PING) directed at a client device. Since latency tests take time to complete, this endpoint creates a background job in WispHub and returns a task_id that can be used to poll for results later.
This endpoint returns immediately with a task ID. Use the Get Ping Result endpoint to retrieve the diagnostic results.

​
Path Parameters

​
service_id
integer
required
ID of the service that owns the assigned IP or device

​
Request Body

​
pings
integer
required
Number of ICMP ping packets to send to the target device

​
Response

​
ok
boolean
required
Indicates whether the request was successful
​
type
string
required
Response type. Values: success, error, info
​
action
string
required
Specific action identifier. Possible values:
  • ping_created - Task created successfully
  • ping_failed - Task creation failed
​
data
object
Response data object
​
message
string
Optional message providing additional context
​
meta
object
Optional metadata object

​
Example Request

curl -X POST https://api.wisphub.com/api/v1/12345/ping/ \
  -H "Content-Type: application/json" \
  -d '{
    "pings": 10
  }'

​
Example Response

{
  "ok": true,
  "type": "success",
  "action": "ping_created",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "message": null,
  "meta": null
}

​
Async Task Workflow

The ping diagnostic follows an asynchronous pattern:
  1. Create Task: Call this endpoint with the service ID and number of pings
  2. Receive Task ID: The response contains a task_id for tracking
  3. Poll for Results: Use the Get Ping Result endpoint with the task ID to retrieve results
  4. Interpret Status: The result endpoint returns connection status: stable, intermittent, no_internet, or error
The WispHub backend processes the ping task asynchronously and returns HTTP 202 internally. Poll the results endpoint periodically until the task completes.

​
Status Codes

  • 200 - Task created successfully
  • 400 - Invalid request parameters
  • 401 - Unauthorized (invalid or missing token)
  • 404 - Service not found
  • 500 - Internal server error