Table of Contents

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:

In addition, third-party libraries are available for the following languages/platforms:

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.
  • GTmetrix Basic users are given up to 20 API credits daily.
  • You can increase your daily API credit allowance by upgrading to GTmetrix PRO.
  • 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
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. See the throttle dropdown in Analysis Options on the Dashboard for sample values. 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
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]: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 PageSpeed 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, file contents have been trimmed, and resource usage data has been included in the HAR file. string
resources.pagespeed URL to download the PageSpeed beacon string
resources.pagespeed_files URL to download the PageSpeed 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
resources.filmstrip The URL to the optional GTmetrix video's filmstrip in JPEG format string

Possible errors

HTTP status code Error message
400 Request must use GET method
404 Test not found
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/test/TtGJTbkv
Response (Started state)
{
    "resources":{},
    "error":"",
    "results":{},
    "state":"started"
}
Response (Completed state)
{
    "resources":{
        "har":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/har",
        "screenshot":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/screenshot",
        "video":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/video",
        "filmstrip":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/filmstrip",
        "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",
        "pagespeed_files":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/pagespeed-files",
        "yslow":"https://gtmetrix.com/api/0.1/test/TtGJTbkv/yslow"
    },
    "error":"",
    "results":{
        "report_url":"https://gtmetrix.com/reports/gtmetrix.com/Cz0AQOjf",
        "html_load_time":"87",
        "html_bytes":"3395",
        "page_load_time":"522",
        "page_bytes":"89229",
        "page_elements":"16",
        "pagespeed_score":"95",
        "yslow_score":"98"
    },
    "state":"completed"
}

Resource usage data

A collection of resource usage values, sampled roughly every hundred milliseconds, is included as a custom field on the pages object of the HAR file. This custom field, named _resourceUsage, is an array containing arrays whose values are structured like so:

Subarray values

Index Description Type
0 The time elapsed since the last sample (in milliseconds) integer
1 The current CPU usage (as a percentage) float
2 The current memory usage (in megabytes) float
3 The amount of data received since the last sample (in bytes) integer
4 The amount of data sent since the last sample (in bytes) integer

Get test resource

GET /api/0.1/test/{test_id}/{resource}

Note that the PageSpeed 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
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]: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
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]: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
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]: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
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]: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
503 Application server temporarily unavailable

cURL example

Request
curl --user [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/status
Response
{
    "api_credits": 20,
    "api_topup": 1483973996
}

Changelog

January 3rd, 2017

  • Added documentation for 503 http status code error.

November 15th, 2016

  • Added documentation for resource usage data.

November 3rd, 2016

  • Added filmstrip to resources for tests that include video.

September 3rd, 2014

  • Added report_pdf_full to resources for the full GTmetrix report PDF.

May 20th, 2014

  • Added rate limiting to report PDF generation.

March 28th, 2014

  • Sync up test options to what's available on the front end (browser, throttle, whitelist/blacklist).
  • Added /browsers and /browsers/{browser_id} endpoints.
  • Added supported browsers to /locations output.

January 13th, 2014

  • Removed the non-working "login" parameter from test.

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 endpoint 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.

Your API Details

An API key is needed to use the GTmetrix REST API or the GTmetrix for WordPress plugin.

You must be logged in to view your API details.

Log in  or  Sign Up