Shortcuts API Documentation - iPerf3 Client & Server

Overview

iPerf3 Client & Server supports x-callback-url integration, allowing you to automate network tests using iOS Shortcuts and other automation apps. This enables powerful workflows like scheduled tests, automatic result logging, and integration with other apps.

💡 Base URL Scheme

All API calls use the URL scheme: iperf3://x-callback-url/

Requirements

iPerf3 Client & Server app installed on your iOS device
iOS 14.0 or later
A configured iPerf3 server to connect to
iOS Shortcuts app (or any app that supports x-callback-url)

Run Test Action

Start a new iPerf3 test with specified parameters.

GETiperf3://x-callback-url/run-test

Parameters

Parameter	Type	Required	Description
`server`	String	Yes	The hostname or IP address of the iPerf3 server
`port`	Integer	No	Server port (default: 5201)
`duration`	Integer	No	Test duration in seconds (default: 10)
`parallel`	Integer	No	Number of parallel streams (default: 1)
`reverse`	Boolean	No	Run reverse test (download) (default: false)
`udp`	Boolean	No	Use UDP instead of TCP (default: false)
`bandwidth`	String	No	Target bandwidth for UDP (e.g., "10M")
`x-success`	String	No	Callback URL on success
`x-error`	String	No	Callback URL on error

Example URL

                iperf3://x-callback-url/run-test?server=iperf.example.com&duration=15&reverse=true&x-success=shortcuts://run-shortcut?name=LogResults
            

Success Response

On success, the app will call your x-success URL with the following parameters:

{
    "testId": "a1b2c3d4",
    "timestamp": "2024-01-15T10:30:00Z",
    "server": "iperf.example.com",
    "status": "completed"
}
            

Get Last Result Action

Retrieve the most recent test result without running a new test.

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

Parameters

Parameter	Type	Required	Description
`x-success`	String	No	Callback URL on success
`x-error`	String	No	Callback URL on error

Example URL

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

Success Response

{
    "testId": "a1b2c3d4",
    "timestamp": "2024-01-15T10:30:00Z",
    "server": "iperf.example.com",
    "downloadSpeed": 945.5,
    "uploadSpeed": 876.2,
    "downloadUnit": "Mbits/sec",
    "uploadUnit": "Mbits/sec",
    "jitter": 0.123,
    "packetLoss": 0.0
}
            

Fetch Result Action

Retrieve a specific test result by its ID.

GETiperf3://x-callback-url/fetch-result

Parameters

Parameter	Type	Required	Description
`testId`	String	Yes	The unique identifier of the test to fetch
`x-success`	String	No	Callback URL on success
`x-error`	String	No	Callback URL on error

Example URL

                iperf3://x-callback-url/fetch-result?testId=a1b2c3d4&x-success=shortcuts://run-shortcut?name=ProcessResult
            

Error Codes

When an error occurs, the app will call your x-error URL with error details:

Code	Description
ERR_CONNECTION_FAILED	Could not connect to the specified server
ERR_TIMEOUT	Connection or test timed out
ERR_INVALID_SERVER	Invalid server hostname or IP address
ERR_NO_RESULTS	No test results available
ERR_TEST_NOT_FOUND	Specified testId does not exist
ERR_INVALID_PARAMS	Missing or invalid parameters
ERR_SERVER_ERROR	iPerf3 server returned an error

Error Response Format

{
    "errorCode": "ERR_CONNECTION_FAILED",
    "errorMessage": "Unable to connect to iperf.example.com:5201",
    "details": "Connection refused"
}
            

FAQ & Troubleshooting

How do I create a shortcut that runs a test?

Open the Shortcuts app, create a new shortcut, and add the "Open URLs" action. Enter your iPerf3 URL scheme with parameters. Add a "Get Contents of URL" action to receive the callback data.

Why isn't the callback working?

Make sure your x-success or x-error URL is properly URL-encoded. The callback URL scheme must be registered on your device (e.g., shortcuts://).

Can I run tests in the background?

iPerf3 tests require the app to be active. However, you can use Shortcuts automation to schedule tests at specific times.

How do I log results to a file?

Use the x-success callback to pass results to another shortcut that saves data to Files, iCloud, or sends it to another app like Numbers or Excel.

⚠️ Important Note

URL parameters must be properly URL-encoded. Special characters in server names or other values should be percent-encoded (e.g., spaces as %20).