GTmetrix REST API
The GTmetrix API offers developers an easy way to utilize GTmetrix's performance testing service. Using the GTmetrix API, you can integrate performance testing into your development environment or into your application.
The GTmetrix API is based on the Web Testing Framework (WTF) Testing Service API which is RESTful API. Please contact us if you have any questions or comments about the API, or if you end up using it in a cool and interesting way!
Libraries
We plan to write libraries/modules for various languages to make using the GTmetrix REST API easier to use. We currently only have a PHP library available:
API Access URL
The base URL for the GTmetrix API is https://gtmetrix.com/api/0.1/. Please note that HTTPS is required.
Authentication
The GTmetrix API uses HTTP Basic Access Authentication as its authentication mechanism. Use your e-mail address as the username and the API key as the password.
You can generate or view your API key at the API Key box at the top of the page.
Request Responses
The GTmetrix API uses the HTTP status codes as defined by RFC 2616 to declare whether an API request was successful or not. The error status codes that the API can return are listed in the documentation below.
All requests (except where noted) return an JSON-encoded string. See the documentation below for the structure of the data.
Errors are returned in the format:
{ "error" : "Error message goes here" }
API Credits
The GTmetrix API uses a credit system to allow access to our servers for analysis requests.
- 1 analysis request = 1 credit.
- Users are given a maximum of 20 credits a day.
- When you first generate an API key, you are given 100 credits (useful for testing purposes).
If you think your application or service will require more API credits, please feel free to upgrade to a GTmetrix PRO account, or contact us.
REST Requests
Start a Test
POST /api/0.1/test
Parameters
| Name | Description | Type | Required | Default |
|---|---|---|---|---|
| url | The URL to test | string | Yes | |
| location | Test location ID | string | No | |
| login | HTTP access authentication type | string (basic, digest) | No | basic |
| login-user | Username for HTTP access authentication | string | No | |
| login-pass | Password for HTTP access authentication | string | No | |
| x-metrix-adblock | Enable AdBlock | integer (0, 1) | No | 0 |
| x-metrix-cookies | Cookies to send with the request | string | No | |
| x-metrix-video | Enable generation of video -- due to extra storage and processing requirements, a video test requires 5 api credits | integer (0, 1) | No | 0 |
Response attributes
| Attribute | Description | Type |
|---|---|---|
| poll_state_url | URL to use to poll test state | string |
| test_id | The test ID | string |
Possible errors
| HTTP status code | Error message |
|---|---|
| 400 | Request must use POST method |
| 400 | Invalid parameter {parameter} |
| 400 | Invalid HTTP Auth Username |
| 400 | Invalid URL |
| 400 | Invalid Test Server Region |
| 402 | Maximum number of API calls reached |
| 429 | Too many concurrent requests from your IP |
cURL example
Request
curl --user user@example.com:e8ddc55d93eb0e8281b255ea236dcc4f \
--form url=http://example.com --form x-metrix-adblock=0 \
https://gtmetrix.com/api/0.1/test
Response
{
"test_id":"TtGJTbkv",
"poll_state_url":"https://gtmetrix.com/api/0.1/test/TtGJTbkv"
}
Get the test state and results/resources (when test complete)
GET /api/0.1/test/{test_id}
The recommended poll interval is 1 second.
Note that the test ID is only valid for 3 days. The GTmetrix report for the URL will be valid for 30 days.
URI values
| Parameter | Description |
|---|---|
| test_id | The test ID returned after starting the test |
Parameters
None
Response attributes
| Name | Description | Type |
|---|---|---|
| state | The current state of the test | string (queued, started, completed, error) |
| error | The error message if state == "error". Empty string if no error. | string |
| results | Summary of test results. Will be an empty object until state == "completed". | hash |
| results.report_url | The URL to the GTmetrix report | string |
| results.pagespeed_score | Page Speed score | integer |
| results.yslow_score | YSlow score | integer |
| results.html_bytes | The HTML size (may be compressed) | integer |
| results.html_load_time | The HTML load time (in milliseconds) | integer |
| results.page_bytes | The total page size | integer |
| results.page_load_time | The page load time (in milliseconds) | integer |
| results.page_elements | The number of page elements | integer |
| resources | URLs of downloadable resources. Will be an empty object until state == "completed". | hash |
| resources.screenshot | URL to download the screenshot | string |
| resources.har | URL to download the HAR file. Note that sensitive info (HTTP auth and cookies) has been removed and file contents have been trimmed from the HAR file. | string |
| resources.pagespeed | URL to download the Page Speed beacon | string |
| resources.pagespeed_files | URL to download the Page Speed optimized files. The files are combined into a single TAR file. | string |
| resources.yslow | URL to download the YSlow beacon | string |
| resources.report_pdf | The URL to the GTmetrix report in PDF format | string |
| resources.video | The URL to the optional GTmetrix video in mp4 format | string |
Possible errors
| HTTP status code | Error message |
|---|---|
| 400 | Request must use GET method |
| 404 | Test not found |
cURL example
Request
curl --user user@example.com:e8ddc55d93eb0e8281b255ea236dcc4f \
https://gtmetrix.com/api/0.1/test/TtGJTbkv
Response (Started state)
{
"resources":{},
"error":"",
"results":{},
"state":"started"
}
Response (Completed state)
{
"resources":{
"report_pdf":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/report-pdf",
"pagespeed":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/pagespeed",
"har":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/har",
"pagespeed_files":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/pagespeed-files",
"yslow":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/yslow",
"screenshot":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/screenshot"
},
"error":"",
"results":{
"page_load_time":"522",
"html_bytes":"3395",
"page_elements":"16",
"report_url":"http://gtmetrix.com/reports/gtmetrix.com/Cz0AQOjf",
"html_load_time":"87",
"page_bytes":"89229",
"pagespeed_score":"95",
"yslow_score":"98"
},
"state":"completed"
}
Get test resource
GET /api/0.1/test/{test_id}/{resource}
Note that the resources are only kept for 3 days. They should be downloaded on job completion if you wish to save them.
URI values
| Parameter | Description |
|---|---|
| test_id | The test ID returned after starting the test |
| resource | Test resource to download: screenshot, har, pagespeed, pagespeed-files, yslow, report-pdf, video |
Parameters
None
Response
Varies based on resource.
Possible errors
| HTTP status code | Error message |
|---|---|
| 400 | Request must use GET method |
| 404 | Test not found |
| 404 | There was an error testing the page, no resources are available |
| 404 | Data not yet available, please wait until test has completed |
| 500 | Resource unavailable |
cURL example
Request
curl --user user@example.com:e8ddc55d93eb0e8281b255ea236dcc4f \
https://gtmetrix.com/api/0.1/test/TtGJTbkv/har
Get a list of test locations
GET /api/0.1/locations
Parameters
None
Response attributes
| Attribute | Description | Type |
|---|---|---|
| {i}.id | The location ID | string |
| {i}.name | The location name | string |
| {i}.default | Whether this is the default location | boolean |
Possible errors
| HTTP status code | Error message |
|---|---|
| 400 | Request must use GET method |
cURL example
Request
curl --user user@example.com:e8ddc55d93eb0e8281b255ea236dcc4f \
https://gtmetrix.com/api/0.1/locations
Response
[
{
"name":"Vancouver, Canada",
"default":true,
"id":"1"
},
{
"name":"London, UK",
"default":false,
"id":"2"
},
{
"name":"Sydney, Australia",
"default":false,
"id":"3"
},
{
"name":"Dallas, USA",
"default":false,
"id":"4"
},
{
"name":"Mumbai, India",
"default":false,
"id":"5"
},
{
"name":"Sao Paulo, Brazil",
"default":false,
"id":"6"
}
]
Get your account status
GET /api/0.1/status
Parameters
None
Response attributes
| Attribute | Description | Type |
|---|---|---|
| api_credits | Amount of API credits remaining | integer |
| api_refill | Unix timestamp for next API topup | integer |
Possible errors
| HTTP status code | Error message |
|---|---|
| 400 | Request must use GET method |
cURL example
Request
curl --user user@example.com:e8ddc55d93eb0e8281b255ea236dcc4f \
https://gtmetrix.com/api/0.1/status
Response
{
"api_credits": 20,
"api_topup": 1369303840
}
Changelog
March 5th, 2013
- Added 429 - Too Many Requests status code if you submit jobs too fast via the API
January 2nd, 2013
- Fixed API status documentation - it's api_refill not api_topup.
March 19th, 2012
- Added /status method to see remaining credits.
February 1st, 2012
- Fixed the login-pass test option (it was using login-password).
January 25th, 2012
- Fixed documentation for results.page_load_time, as the value is in milliseconds, not seconds and is an integer, not a float.
- results.html_load_time has been changed from seconds/float to milliseconds/integer to match page_load_time.