Shortcuts API - iPerf3 Client & Server

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:

Run iPerf Test

Runs a test with configurable server, protocol, direction, and timing. Typical default duration in shortcuts flow is 5 seconds.

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

Starts a new test and optionally returns via callback URLs.

Parameter	Type	Required	Description
`server`	String	Yes	Hostname or IP of the iPerf3 endpoint.
`protocol`	String	No	`tcp` (default) or `udp`.
`direction`	String	No	`download`, `upload`, or `bidirectional`.
`durationSec`	Integer	No	Duration in seconds. Common default in automation is 5.
`streams`	Integer	No	Parallel stream count.
`x-success`	String	No	Callback URL for success result payload.
`x-error`	String	No	Callback URL for error payload.

GETiperf3cs://x-callback-url/get-last-result

Returns the latest local result, useful for periodic logging workflows.

Parameter	Type	Required	Description
`x-success`	String	No	Callback URL for successful payload.
`x-error`	String	No	Callback URL for errors.

GETiperf3cs://x-callback-url/test-server

Checks endpoint reachability and returns status/latency metadata.

Parameter	Type	Required	Description
`server`	String	Yes	Hostname or IP to test.
`port`	Integer	No	Port value (default 5201).

Examples

Run test with callbacks

iperf3cs://x-callback-url/run-test?server=iperf.example.com&protocol=tcp&direction=download&durationSec=8&x-success=shortcuts://run-shortcut?name=StoreResult
                

Read latest result

iperf3cs://x-callback-url/get-last-result?x-success=shortcuts://run-shortcut?name=PushSummary
                

Terminal launch on macOS

open "iperf3cs://x-callback-url/run-test?server=10.0.1.5&protocol=udp&direction=bidirectional&durationSec=5"
                

Typical payload fields

{
  "testId": "A8B3D9",
  "timestamp": "2026-02-26T09:42:10Z",
  "server": "iperf.example.com",
  "protocol": "tcp",
  "downloadMbps": 942.7,
  "uploadMbps": 876.4,
  "status": "completed"
}
                

Error Handling

When an action fails and x-error is present, the callback receives an error object.

Code	Description
ERR_CONNECTION_FAILED	Unable to connect to endpoint.
ERR_TIMEOUT	Connection or test exceeded timeout.
ERR_INVALID_SERVER	Malformed host or unreachable address.
ERR_NO_RESULTS	No saved results for the requested action.
ERR_INVALID_PARAMS	Missing or invalid required parameters.

{
  "errorCode": "ERR_CONNECTION_FAILED",
  "errorMessage": "Could not reach 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?

Use test-server first, then run a throughput test only if the endpoint check succeeds.

Shortcuts and x-callback-url