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.

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
browser Browser ID string No
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
x-metrix-throttle Throttle the connection. Speed measured in Kbps, latency in ms. string (up/down/latency) No
x-metrix-whitelist Only load resources that match one of the URLs on this list. This uses the same syntax as the web front end. string No
x-metrix-blacklist Prevent loading of resources that match one of the URLs on this list. This occurs after the whitelist is applied. string No

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
400 Supplied Test Server Region is currently down
400 Invalid Browser Selection
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 (# of resources) 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.report_pdf_full The URL to the full GTmetrix report (includes recommendation details) 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",
        "report_pdf_full":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/report-pdf?full=1",
        "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 Page Speed optimized files are only kept for 3 days. They should be downloaded on job completion if you wish to save them.

Generating a report PDF is a resource intensive task and as a result, is rate limited to 10 report PDFs per minute.

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
429 Rate limit exceeded, please try again later
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
{i}.browsers List of browser ID's supported by this location array of strings

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
[
    {
        "id":"1",
        "name":"Vancouver, Canada",
        "default":true,
        "browsers":["1","3"]
    },
    {
        "id":"2",
        "name":"London, UK",
        "default":false,
        "browsers":["1","3"]
    },
    {
        "id":"3",
        "name":"Sydney, Australia",
        "default":false,
        "browsers":["1","3"]
    },
    {
        "id":"4",
        "name":"Dallas, USA",
        "default":false,
        "browsers":["1","3"]
    },
    {
        "id":"5",
        "name":"Mumbai, India",
        "default":false,
        "browsers":["1"]
    },
    {
        "id":"6",
        "name":"Sao Paulo, Brazil",
        "default":false,
        "browsers":["1","3"]
    }
]

Get a list of browsers

GET /api/0.1/browsers

Parameters

None

Response attributes

Attribute Description Type
{i}.id The browser ID string
{i}.name The browser display name string
{i}.platform The browser platform (desktop/android) string
{i}.device The browser device type (phone/tablet); if applicable string
{i}.browser The browser (firefox/chrome) string
{i}.features.adblock Whether this browser supports AdBlock boolean
{i}.features.cookies Whether this browser supports specifying cookies boolean
{i}.features.filtering Whether this browser supports URL whitelist/blacklists boolean
{i}.features.http_auth Whether this browser supports HTTP authentication boolean
{i}.features.throttle Whether this browser supports connection throttling boolean
{i}.features.video Whether this browser supports video generation 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/browsers
Response
[
    {
        "id":"1",
        "name":"Firefox (Desktop)",
        "platform":"desktop",
        "device":"",
        "browser":"firefox",
        "features": {
            "adblock":true,
            "cookies":true,
            "filtering":true,
            "http_auth":true,
            "throttle":true,
            "video":true
        }
    },
    {
        "id":"3",
        "name":"Chrome (Desktop)",
        "platform":"desktop",
        "device":"",
        "browser":"chrome",
        "features":{
            "adblock":true,
            "cookies":true,
            "filtering":false,
            "http_auth":false,
            "throttle":true,
            "video":true
        }
    }
]

Get browser details

GET /api/0.1/browsers/{browser_id}

Parameters

None

Response attributes

See /browsers response (except it's for a single record, not all records).

Possible errors

HTTP status code Error message
400 Request must use GET method
404 Browser not found

cURL example

Request
curl --user user@example.com:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/browsers/1
Response
{
        "id":"1",
        "name":"Firefox (Desktop)",
        "platform":"desktop",
        "device":"",
        "browser":"firefox",
        "features": {
            "adblock":true,
            "cookies":true,
            "filtering":true,
            "http_auth":true,
            "throttle":true,
            "video":true
        }
}

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": 1414881633
}

Changelog

September 3rd, 2014

May 20th, 2014

March 28th, 2014

January 13th, 2014

March 5th, 2013

January 2nd, 2013

March 19th, 2012

February 1st, 2012

January 25th, 2012

Your API Details

You must be logged in to generate a key.