Run iPerf Test
Runs a test with configurable server, protocol, direction, and timing. Typical default duration in shortcuts flow is 5 seconds.
Developer docs
Shortcuts and x-callback-url
Automate throughput checks, endpoint validation, and result collection with built-in actions and callback endpoints.
Overview
iPerf3 Client & Server exposes two automation layers:
- Native Apple Shortcuts actions (recommended for most users)
- x-callback-url endpoints for scriptable app-to-app workflows
Base URL Scheme
Use iperf3cs://x-callback-url/... for callback-based automation.
Compatibility
Current Apple platform requirements are iOS/iPadOS 16.6+, macOS 13.5+, and visionOS 1.0+.
Built-in Shortcuts Actions
These actions are available directly in the Apple Shortcuts app:
Get Last Result
Returns the latest completed result from local history.
Test Server
Checks endpoint availability before a full run.
List Servers
Returns configured servers for menu-driven automation.
x-callback-url Endpoints
GETiperf3cs://x-callback-url/run-test
Runs a test and returns the result through the callback URLs.
| Parameter | Type | Required | Description |
|---|---|---|---|
serverId | String | No | Saved server to use: host:port, a server UUID, or default. Omit it and the default server is used. |
serverName | String | No | Pick the server by its saved name instead of serverId. Takes precedence when both are present. |
autoAdd | Boolean | No | Create the server if it is not in the library yet. addServer is accepted as an alias. |
durationSec | Integer | No | Test length in seconds. Defaults to 5. |
protocol | String | No | tcp (default) or udp. |
direction | String | No | download, upload or bidirectional. |
streams | Integer | No | Parallel stream count. |
bandwidthMbps | Number | No | Target bandwidth for UDP tests, in Mbps. |
format | String | No | json (default) or text. |
x-success | String | No | Callback URL. Receives result with the payload, or resultRef when the payload is too large to pass in a URL. |
x-error | String | No | Callback URL. Receives errorCode and errorMessage. |
x-cancel | String | No | Callback URL for a cancelled run. |
GETiperf3cs://x-callback-url/get-last-result
Returns the most recent saved result. Useful for periodic logging.
| Parameter | Type | Required | Description |
|---|---|---|---|
serverId | String | No | Limit the lookup to one server: host:port, a UUID, or default. Omit it for the latest result overall. |
serverName | String | No | Same lookup by saved name. Takes precedence over serverId. |
format | String | No | json (default) or text. |
x-success | String | No | Callback URL. Receives result with the payload, or resultRef when the payload is too large to pass in a URL. |
x-error | String | No | Callback URL. Receives errorCode and errorMessage. |
x-cancel | String | No | Callback URL for a cancelled run. |
GETiperf3cs://x-callback-url/fetch-result
Fetches a payload the app handed back as a reference. When a result is too large for a callback URL, the app returns <code>resultRef</code> instead of <code>result</code>, and this endpoint exchanges that reference for the full payload.
| Parameter | Type | Required | Description |
|---|---|---|---|
resultRef | String | Yes | Reference returned earlier in place of result. |
format | String | No | json (default) or text. |
x-success | String | No | Callback URL. Receives result with the payload, or resultRef when the payload is too large to pass in a URL. |
x-error | String | No | Callback URL. Receives errorCode and errorMessage. |
x-cancel | String | No | Callback URL for a cancelled run. |
Examples
Run test with callbacks
iperf3cs://x-callback-url/run-test?serverId=iperf.example.com:5201&autoAdd=1&protocol=tcp&direction=download&durationSec=8&format=json&x-success=shortcuts://run-shortcut?name=StoreResult Read latest result
iperf3cs://x-callback-url/get-last-result?format=json&x-success=shortcuts://run-shortcut?name=PushSummary Terminal launch on macOS
open "iperf3cs://x-callback-url/run-test?serverId=10.0.1.5:5201&protocol=udp&direction=bidirectional&durationSec=5" Typical payload fields
{
"success": true,
"startTime": "2026-08-21T09:42:02Z",
"endTime": "2026-08-21T09:42:10Z",
"duration": 8,
"receivedMegabitsPerSecond": 942.7,
"sentMegabitsPerSecond": 876.4,
"receivedBytes": 942700000,
"summaryText": "942.7 Mbps down, 876.4 Mbps up"
} Error Handling
When an action fails and x-error is present, the callback receives an error object.
| Code | Description |
|---|---|
| invalidParameter | A parameter is missing, malformed or out of range. |
| serverNotFound | No saved server matched the lookup, and autoAdd was not set. |
| networkUnavailable | The device has no usable network path to the endpoint. |
| connectionTimeout | The connection or the test exceeded its timeout. |
| testFailed | The test started and ended without a usable result. |
| cancelled | The run was cancelled before it finished. |
| requiresAppOpen | The action needs the app in the foreground. |
| unsupportedOnOSVersion | The action is not available on this OS version. |
{
"errorCode": "serverNotFound",
"errorMessage": "No saved server matches iperf.example.com:5201"
} FAQ
Why does my callback not return to Shortcuts?
Ensure callback URLs are URL-encoded and the scheme is allowed on your device. Avoid spaces or unescaped symbols in query values.
Can tests run fully in the background?
For reliable execution, keep the app active during test runtime. Use Shortcuts scheduling to trigger runs at specific times.
What is the safest integration pattern?
Set x-error on every call and branch on errorCode. Start with a short durationSec=5 run: if it comes back serverNotFound or connectionTimeout, there is no point running a long test.