GTmetrix REST API v0.1

The GTmetrix API offers developers an easy way to utilize the GTmetrix 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; a 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 currently have a PHP library available for use with our REST API v0.1:

• Services_WTF_Test PHP library
• Sample PHP code

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

• Node.js
• .NET
• Python
• PHP
• Java
• Objective-C
• Ruby
• Erlang

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 your API key as the password.

We recommend using your HTTP client's built-in basic authentication handling, like in the curl examples below, which automatically generates the correct Authorization header and appends it to your request. You can also generate the Authorization header yourself by following the specification instructions.

You can generate or view your API key at the API Key box at the top of the page.

Note that if you are accessing the API using an API key generated from a GTmetrix Team plan with role of Viewer, you will not be able to generate tests, delete reports or create PDF reports.

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 Rate Limiting

The GTmetrix API has a global rate limit on all the API endpoints to prevent accidental or deliberate flooding of requests to the API service. Limits have been chosen that should be high enough for any reasonable API usage. If you are hitting the limits, consider increasing your retry times or contact us to discuss your usage scenario.

The rate-limit state is communicated via X-RateLimit-* response headers, loosely following the specification guidelines:

X-RateLimit-Limit: {request-quota}, {request-quota};window={time-window}
X-RateLimit-Remaining: {requests-remaining}
X-RateLimit-Reset: {time-remaining}

If you exceed this limitation, the API will respond with a 429 error to any request until the end of the rate limit window.

API Credits

The GTmetrix API uses a credit system to allow access to our servers for analysis requests.

• 1 analysis request = 0.7 credits (3.5 credits for a video request).
• GTmetrix Basic users are given up to 5 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).

Please note that your API credits only refill when they fall below your account's Daily API Credit—credits do not accumulate past your account's Daily API Credit allowance.

For example, a GTmetrix Basic account has a daily allocation of 5 credits. A refill of these credits (back to 5) will occur on the next refill period and only when your remaining credits drop below 5.

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

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    -F url=http://example.com -F x-metrix-adblock=0 \
    https://gtmetrix.com/api/0.1/test

{
    "test_id":"TtGJTbkv",
    "poll_state_url":"https://gtmetrix.com/api/0.1/test/TtGJTbkv",
    "credits_left":78
}

Get the test state and results/resources (when test complete)

GET /api/0.1/test/{test_id}

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/test/TtGJTbkv

{
    "resources":{},
    "error":"",
    "results":{},
    "state":"started"
}

{
    "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"
}

Get test resource

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

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/test/TtGJTbkv/har

Get a list of available test locations

GET /api/0.1/locations

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/locations

[
    {
        "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":"San Antonio, USA",
        "default":false,
        "browsers":["1","3"]
    },
    {
        "id":"5",
        "name":"Mumbai, India",
        "default":false,
        "browsers":["1,"3"]
    },
    {
        "id":"6",
        "name":"Sao Paulo, Brazil",
        "default":false,
        "browsers":["1","3"]
    },
    {
        "id":"7",
        "name":"Hong Kong, China",
        "default":false,
        "browsers":["1","3"]
    }
]

Get a list of available browsers

GET /api/0.1/browsers

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/browsers

[
    {
        "id":"1",
        "name":"Firefox (Desktop)",
        "platform":"desktop",
        "device":"",
        "browser":"firefox",
        "features": {
            "adblock":true,
            "cookies":true,
            "filtering":true,
            "http_auth":true,
            "throttle":true,
            "video":true,
            "dns":true,
            "user_agent":true,
            "resolution":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,
            "dns":true,
            "user_agent":true,
            "resolution":true
        }
    }
]

Get browser details

GET /api/0.1/browsers/{browser_id}

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/browsers/1

{
    "id":"1",
    "name":"Firefox (Desktop)",
    "platform":"desktop",
    "device":"",
    "browser":"firefox",
    "features": {
        "adblock":true,
        "cookies":true,
        "filtering":true,
        "http_auth":true,
        "throttle":true,
        "video":true,
        "dns":true,
        "user_agent":true,
        "resolution":true
    }
}

Get your account status

GET /api/0.1/status

curl -u [email protected]:e8ddc55d93eb0e8281b255ea236dcc4f \
    https://gtmetrix.com/api/0.1/status

{
    "api_credits": 20,
    "api_refill": 1722139019
}

Reference Values

List of Simulated Devices

Note that this parameter is only available with GTmetrix PRO plans. Learn more.

Connection Throttling

These are the default values for connection throttling available in the Dashboard. You can also pass in a custom connection string with down/up/latency values in Kbps.

Changelog

May 3rd, 2021

• API Credit costs scaled down
• Added API endpoint rate limiting

June 4th, 2020

• Renamed x-metrix-whitelist/x-metrix-blacklist to x-metrix-allow-url/x-metrix-block-url. Old parameters still work for backwards compatibility.

June 1st, 2020

• Fixed dom_content_loaded_duration to not always return null.

November 9th, 2018

• Updated simulate device reference values with new devices.

September 17th, 2018

• Added reference values for both simulate device and connection throttling parameters.

November 24th, 2017

• Added new timing to results: first_contentful_paint_time

October 23rd, 2017

• Fixed documentation for x-metrix-browser-rotate (it was incorrectly documented as x-metrix-rotate).

October 12th, 2017

• Added support for Developer Toolkit functionality including 7 new options: x-metrix-dns, x-metrix-simulate-device, x-metrix-user-agent, x-metrix-browser-width, x-metrix-browser-height, x-metrix-browser-dppx and x-metrix-browser-rotate.
• Added documentation for Developer Toolkit options.

June 14th, 2017

• Added an api_credits variable to a request response.

February 8th, 2017

• Added new timings to results: redirect_duration, connect_duration, backend_duration, first_paint_time, dom_interactive_time, dom_content_loaded_time, dom_content_loaded_duration, onload_time, onload_duration, fully_loaded_time, rum_speed_index.
• Added x-metrix-stop-onload option to stop test onload.
• results.html_load_time has been modified to be TTFB instead of including the time to download the page as well.

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, URL filtering).
• 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.