Catchpoint WebPageTest Documentation

WebPageTest REST API

The WebPageTest REST API provides a way for you to programatically interact with WebPageTest and all of its functionality, enabling you to integrate WebPageTest data into your existing processes and workflows in the way that best suits your needs.

The official Node.js WebPageTest API wrapper—built by Marcel Duran—provides a convenient NodeJS interface for the API and also exposes handy a CLI.

There's also an ever-growing repository of common recipes for the the API, using the Node.js wrapper to help you get started.

Authentication

The WebPageTest API uses API keys to authenticate all tests submitted to the public WebPageTest testing agents.

API keys may or may not be required for requests made to any private instances you maintain on your own. Check with the administrator of your private instance to verify.

You can pass your API key along with tests requests by using the X-WPT-API-KEY HTTP header.

curl --request POST --url https://www.webpagetest.org/runtest.php?url={your_domain} --header "X-WPT-API-KEY: {your_api_key}"

Your API keys are directly tied to your account, so be sure to keep them secure. Avoid sharing them in any public area, such as GitHub or client-side code.

Status Codes

The WebPageTest API uses HTTP response codes in the statusCode property of return objects to indicate whether an API request was sucessful or failed. Codes in the 1xx range indicate that the requested test is not yet ready. Codes in the 4xx range indicate there was an error with the requested test. A status code of 200 indicates a successful test run.

Status Code Description
100 Test started
101 Test is in the queue
102 The test server is unreachable
200 The test is complete
400 A test with the testId passed was not found
401 The testId is valid, but no test was found in the work queue
402 The test with the testId passed was cancelled

Running a Test

To submit a test to the WebPageTest agents, you submit either a POST or GET request to the https://www.webpagetest.org/runtest.php endpoint, along with your API key, the URL you want to test and any optional parameters to configure your how the test is run and what data it will return when completed.

Response Format

By default, after a successful request to the /runtest.php endpoint, you will be redirected to the results page.

You can optionally set the response format using the f parameter to return either an XML response (f=xml) or JSON response (f=json).

//this will result in a redirect
curl --request POST https://www.webpagetest.org/runtest.php?url={your_domain} --header "X-WPT-API-KEY: {your_api_key}"

//this will return an XML response
curl --request POST https://www.webpagetest.org/runtest.php?url={your_domain}&f=xml --header "X-WPT-API-KEY: {your_api_key}"

//this will return a JSON response
curl --request POST https://www.webpagetest.org/runtest.php?url={your_domain}&f=json --header "X-WPT-API-KEY: {your_api_key}"

Here's an example response when the format parameter is provided to the endpoint:

{
	"statusCode": 200,
	"statusText": "Ok",
	"data": {
		"testId": "210304_Ai8T_b21a9c202a106632afd2c6485bda4211",
		"jsonUrl": "https://www.webpagetest.org/jsonResult.php?test=210304_Ai8T_b21a9c202a106632afd2c6485bda4211",
		"xmlUrl": "https://www.webpagetest.org/xmlResult/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/",
		"userUrl": "https://www.webpagetest.org/result/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/",
		"summaryCSV": "https://www.webpagetest.org/result/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/page_data.csv",
		"detailCSV": "https://www.webpagetest.org/result/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/requests.csv"
	}
}
<response>
	<statusCode>200</statusCode>
	<statusText>Ok</statusText>
	<data>
		<testId>210304_Ai8T_b21a9c202a106632afd2c6485bda4211</testId>
		<xmlUrl>https://www.webpagetest.org/xmlResult/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/</xmlUrl>
		<userUrl>https://www.webpagetest.org/result/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/</userUrl>
		<summaryCSV>https://www.webpagetest.org/result/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/page_data.csv</summaryCSV>
		<detailCSV>https://www.webpagetest.org/result/210304_Ai8T_b21a9c202a106632afd2c6485bda4211/requests.csv</detailCSV>
		<jsonUrl>https://www.webpagetest.org/jsonResult.php?test=210304_Ai8T_b21a9c202a106632afd2c6485bda4211</jsonUrl>
	</data>
</response>

The response object contains the following attributes:

Full List of Parameters

Specifying connectivity

If the connectivity is not specified, by default you will get the Cable (5/1 Mbps, 28ms RTT) profile. The connectivity is specified using the location parameter in the format:

location:browser.connectivity or location.connectivity

For example:

Public instances of WebPageTest provide a number of out-of-the box connection profiles for you to use to run tests:

Browser is only required in a Chrome/Firefox install where wptdriver is configured for multiple browsers.

Available locations for API calls

On the public instance with an API key that starts with "A.", only locations listed [here](curl --request GET --url https://www.webpagetest.org/getLocations.php?&f=html --header "X-WPT-API-KEY: {your_api_key}") are available for API calls. Others will return invalid location when requested.

Examples

Test www.aol.com and redirect to the results page:

http://www.webpagetest.org/runtest.php?url=www.aol.com

Test www.aol.com 9 times, first view only and redirect to the results page:

http://www.webpagetest.org/runtest.php?url=www.aol.com&runs=9&fvonly=1

Test www.aol.com 2 times and get the response as xml with the request ID "12345" embedded in the response:

http://www.webpagetest.org/runtest.php?url=www.aol.com&runs=2&f=xml&r=12345

Check test status

You can check the status of a test by doing a GET to http://www.webpagetest.org/testStatus.php with your test id and an optional format parameter. You will get a HTTP 200 response to the request itself indicating that the request was parsed, as well as a return object with details about the test run itself. Alternatively, you can check the status of a test by doing a GET to a results endpoint.

Response Format

By default, the /testStatus.php endpoint returns a JSON object. Alternatively, you can request the response object be returned as XML by passing the format (f) parameter.

//this will return a JSON response
https://www.webpagetest.org/testStatus.php?test={your_test_id}

//this will return an XML response
https://www.webpagetest.org/testStatus.php?test={your_test_id}&f=xml
{
   "statusCode":200,
   "statusText":"Test Complete",
   "data":{
      "statusCode":200,
      "statusText":"Test Complete",
      "id":"210304_Ai8T_b21a9c202a106632afd2c6485bda4211",
      "completeTime":"03\/05\/21 16:44:35",
      "testInfo":{
         "url":"https:\/\/docs.webpagetest.org",
         "runs":3,
         "fvonly":1,
         "web10":0,
         "ignoreSSL":0,
         "label":"Netlify Deploy undefined",
         "priority":5,
         "location":"Dulles",
         "browser":"Chrome",
         "connectivity":"Cable",
         "bwIn":5000,
         "bwOut":1000,
         "latency":28,
         "plr":"0",
         "tcpdump":0,
         "timeline":0,
         "trace":0,
         "bodies":0,
         "netlog":0,
         "standards":0,
         "noscript":0,
         "pngss":0,
         "iq":0,
         "keepua":0,
         "mobile":0,
         "scripted":0
      },
      "remote":false,
      "testsExpected":3,
      "runs":3,
      "fvonly":1,
      "location":"Dulles"
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <statusCode>200</statusCode>
   <statusText>Test Complete</statusText>
   <data>
      <statusCode>200</statusCode>
      <statusText>Test Complete</statusText>
      <id>210304_Ai8T_b21a9c202a106632afd2c6485bda4211</id>
      <completeTime>03/09/21 14:15:34</completeTime>
      <testInfo>
         <url>https://docs.webpagetest.org</url>
         <runs>3</runs>
         <fvonly>1</fvonly>
         <web10>0</web10>
         <ignoreSSL>0</ignoreSSL>
         <label>Netlify Deploy undefined</label>
         <priority>5</priority>
         <location>Dulles</location>
         <browser>Chrome</browser>
         <connectivity>Cable</connectivity>
         <bwIn>5000</bwIn>
         <bwOut>1000</bwOut>
         <latency>28</latency>
         <plr>0</plr>
         <tcpdump>0</tcpdump>
         <timeline>0</timeline>
         <trace>0</trace>
         <bodies>0</bodies>
         <netlog>0</netlog>
         <standards>0</standards>
         <noscript>0</noscript>
         <pngss>0</pngss>
         <iq>0</iq>
         <keepua>0</keepua>
         <mobile>0</mobile>
         <scripted>0</scripted>
      </testInfo>
      <remote />
      <testsExpected>3</testsExpected>
      <runs>3</runs>
      <fvonly>1</fvonly>
      <location>Dulles</location>
   </data>
</response>

The response object contains the following attributes:

Full List of Parameters

Retrieving test results

To retrieve the results of a test run, you can use either the https://www.webpagetest.org/xmlResult.php (to return an XML response) or https://www.webpagetest.org/jsonResult.php (to return a JSON response) endpoint. The endpoint will return a response containing some information about the test itself, as well as an object containing all the metrics recorded across each test run.

As noted in Status Codes, response codes in the 1xx range indicate that the requested test is not yet ready. Codes in the 4xx range indicate there was an error with the requested test. A status code of 200 indicates a successful test run.

Response Format

The results endpoints will return a different response type depending on the endpoint you use.

//this will result in an XML response
https://www.webpagetest.org/xmlResult.php

//this will return a JSON response
https://www.webpagetest.org/jsonResult.php

Here's an example response, truncated for brevity:

{
  "data": {
    "id": "230524_BiDcEX_B06",
    "url": "http://www.webpagetest.com",
    "summary": "https://www.webpagetest.org/results.php?test=230524_BiDcEX_B06",
    "testUrl": "http://www.webpagetest.com",
    "location": "Dulles:Chrome",
    "from": "Dulles, VA - <b>Chrome</b> - <b>Cable</b>",
    "connectivity": "Cable",
    "bwDown": 5000,
    "bwUp": 1000,
    "latency": 28,
    "plr": "0",
    "shaperLimit": 0,
    "mobile": 0,
    "completed": 1616896955,
    "testRuns": 1,
    "fvonly": false,
    "successfulFVRuns": 1,
    "successfulRVRuns": 1,
    "average": {
        //all metrics for this  run
    },
    "standardDeviation": {
        //all metrics for this run
    },
    "median": {
        //all metrics for this run
    },
    "runs": {
        //all metrics for all runs
    }
  },
  "statusCode": 200,
  "statusText": "Test Complete",
  "webPagetestVersion": "20.06"
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <statusCode>200</statusCode>
   <statusText>Ok</statusText>
   <webPagetestVersion>20.06</webPagetestVersion>
   <data>
      <testId>230524_BiDcEX_B06</testId>
      <summary>https://www.webpagetest.org/result/230524_BiDcEX_B06/</summary>
      <testUrl>http://www.webpagetest.com</testUrl>
      <location>Dulles:Chrome</location>
      <from>
         Dulles, VA -
         <b>Chrome</b>
         -
         <b>Cable</b>
      </from>
      <connectivity>Cable</connectivity>
      <bwDown>5000</bwDown>
      <bwUp>1000</bwUp>
      <latency>28</latency>
      <plr>0</plr>
      <mobile>0</mobile>
      <completed>Sun, 28 Mar 2021 02:02:35 +0000</completed>
      <runs>1</runs>
      <successfulFVRuns>1</successfulFVRuns>
      <successfulRVRuns>1</successfulRVRuns>
      <average>...</average>
      <standardDeviation>...</standardDeviation>
      <median>...</median>
      <run>...</run>
   </data>
</response>

There are a lot of metrics recorded by WebPageTest and exposed via the API. We're working on documenting them all. In the meantime, feel free to poke at some sample results (in either JSON or XML format) to see what's available.

Full List of Parameters

Cancelling Tests

To cancel a test that has not started running, you can use the http://www.webpagetest.org/cancelTest.php endpoint.

curl http://www.webpagetest.org/cancelTest.php?test=210328_XiMJ_3c426d8c00c689f22f4097cbb1dfd697 --header "X-WPT-API-KEY: {your_api_key}"

Full List of Parameters

Retrieving Available Locations

You can request a list of available WebPageTest agents as well as the number of pending tests for each using the https://www.webpagetest.org/getLocations.php endpoint.

Response Format

By default, a successful request to the /getLocations.php endpoint, results an XML response. You can optionally set the response format using the f parameter to request a JSON response (f=json).

If you pass the callback parameter in conjunction with using f=json, the endpoint will return a JSONP response with the JSON wrapped in the given callback function name.

//this will result in an XML response
https://www.webpagetest.org/getLocations.php

//this will return a JSON response
https://www.webpagetest.org/getLocations.php?f=json

//this will return a JSONP response, with the JSON wrapped in myCallback()
https://www.webpagetest.org/getLocations.php?f=json&callback=myCallback

Here's an example response from the /getLocations.php endpoint, (truncated for brevity):

{
   "statusCode":200,
   "statusText":"Ok",
   "data":{
      "Dulles":{
         "Label":"Dulles, VA USA (Desktop, Android, iOS)",
         "location":"Dulles",
         "Browsers":"Chrome,Chrome Beta,Chrome Canary,Firefox,Firefox Nightly,Firefox ESR,Brave",
         "status":"OFFLINE",
         "labelShort":"Dulles, VA",
         "node":"4789",
         "group":"North America",
         "PendingTests":{
            "p1":0,
            "p2":0,
            "p3":0,
            "p4":0,
            "p5":0,
            "p6":0,
            "p7":0,
            "p8":0,
            "p9":0,
            "Total":0,
            "HighPriority":0,
            "LowPriority":0,
            "Testing":0,
            "Idle":0,
            "TestAgentRatio":0
         }
      },
      "ec2-us-east-1":{
         "Label":"Virginia - EC2 (Chrome,Firefox)",
         "location":"ec2-us-east-1",
         "Browsers":"Chrome,Chrome Beta,Chrome Canary,Firefox,Firefox Nightly,Firefox ESR,Brave",
         "status":"OK",
         "labelShort":"Virginia USA - EC2 ",
         "node":"4789",
         "default":true,
         "group":"North America",
         "PendingTests":{
            "p1":0,
            "p2":0,
            "p3":0,
            "p4":0,
            "p5":0,
            "p6":0,
            "p7":0,
            "p8":0,
            "p9":0,
            "Total":12,
            "HighPriority":0,
            "LowPriority":0,
            "Testing":12,
            "Idle":34,
            "TestAgentRatio":0.2608695652173913
         }
      }
      ...
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <statusCode>200</statusCode>
   <statusText>Ok</statusText>
   <data>
      <location>
         <id>Dulles_MotoG4</id>
         <Label>Moto G (gen 4)</Label>
         <location>Dulles_MotoG4</location>
         <Browsers>Moto G4 - Chrome,Moto G4 - Chrome Canary,Moto G4 - Chrome Beta,Moto G4 - Chrome Dev,Moto G4 - Samsung Internet,Moto G4 - UC Browser,Moto G4 - UC Mini,Moto G4 - Opera Mini (Extreme),Moto G4 - Opera Mini (High),Moto G4 - Firefox,Moto G4 - Chrome,Moto G4 - Chrome Canary,Moto G4 - Chrome Beta,Moto G4 - Chrome Dev,Moto G4 - Samsung Internet,Moto G4 - UC Browser,Moto G4 - UC Mini,Moto G4 - Opera Mini (Extreme),Moto G4 - Opera Mini (High),Moto G4 - Firefox</Browsers>
         <status>OK</status>
         <labelShort>Dulles, VA</labelShort>
         <group>Android Devices - Dulles, VA</group>
         <PendingTests>
            <p1>0</p1>
            <p2>0</p2>
            <p3>0</p3>
            <p4>0</p4>
            <p5>0</p5>
            <p6>1</p6>
            <p7>0</p7>
            <p8>0</p8>
            <p9>0</p9>
            <Total>45</Total>
            <HighPriority>29</HighPriority>
            <LowPriority>1</LowPriority>
            <Testing>15</Testing>
            <Idle>0</Idle>
            <TestAgentRatio>3</TestAgentRatio>
         </PendingTests>
      </location>
      <location>
         <id>Dulles_MotoG6</id>
         <Label>Moto G (gen 6)</Label>
         <location>Dulles_MotoG6</location>
         <Browsers>Moto G6 - Chrome,Moto G6 - Chrome Canary,Moto G6 - Chrome Beta,Moto G6 - Chrome Dev,Moto G6 - UC Browser,Moto G6 - UC Mini,Moto G6 - Opera Mini (Extreme),Moto G6 - Opera Mini (High),Moto G6 - Firefox,Moto G6 - Chrome,Moto G6 - Chrome Canary,Moto G6 - Chrome Beta,Moto G6 - Chrome Dev,Moto G6 - UC Browser,Moto G6 - UC Mini,Moto G6 - Opera Mini (Extreme),Moto G6 - Opera Mini (High),Moto G6 - Firefox</Browsers>
         <status>OK</status>
         <labelShort>Dulles, VA</labelShort>
         <group>Android Devices - Dulles, VA</group>
         <PendingTests>
            <p1>0</p1>
            <p2>0</p2>
            <p3>0</p3>
            <p4>0</p4>
            <p5>3</p5>
            <p6>0</p6>
            <p7>0</p7>
            <p8>0</p8>
            <p9>0</p9>
            <Total>33</Total>
            <HighPriority>29</HighPriority>
            <LowPriority>3</LowPriority>
            <Testing>1</Testing>
            <Idle>0</Idle>
            <TestAgentRatio>33</TestAgentRatio>
         </PendingTests>
      </location>
      ...
   </data>
</response>

You can also optionally pass a location parameter referencing an individual location ID to be able to check the status of a single location at a time.

https://webpagetest.org/getLocations.php?f=json&location=ec2-us-east-1

Full list of parameters

  • f optional
    The format to return. Set to "xml" to request an XML response; set to "json" to request a JSON-encoded response. If no format parameter is passed, the API call will default to an XML reponse.
  • callback optional
    Callback function name. When used with f=json, the API will return an JSONP response by wrapping the JSON object with the provided callback name.
  • r (string)
    Request ID. Will echo back in the response object.
  • location optional
    Location ID. If provided, the response will return only the status and information for the specified location.

Checking Remaining Test Balance

To check how how many API tests you have remaining in your current billing period, you can use the https://webpagetest.org/testBalance.php endpoint.

Response Format

By default, a sucessful request to the /testBalance.php endpoint will result in an JSON response. You can optionally set the response format using the f parameter to request an XML response (f=xml).

//this will result in a JSON response
curl https://webpagetest.org/testBalance.php --header "X-WPT-API-KEY: {your_api_key}"

//this will result in an XML response
curl https://webpagetest.org/testBalance.php?f=xml --header "X-WPT-API-KEY: {your_api_key}"

Here's an example response:

{
    "data": {
        "remaining": 1175
    }
}
<response>
   <data>
      <remaining>1175</remaining>
   </data>
</response>

If your API key is invalid, or expired, you will instead see an error property with an appropriate message.

{
    "data": {
        "remaining": "Error validating API Key Account"
    }
}
<response>
   <data>
      <remaining>Error validating API Key Account</remaining>
   </data>
</response>

Full List of Parameters