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

Table of Contents

GTmetrix REST API v2.0

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.

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 also provide an OpenAPI v3.02 specification of this API. Use it with OpenAPI-compatible tools to jump start your GTmetrix integration: Download

API Access URL

The base URL for the GTmetrix API is https://gtmetrix.com/api/2.0/. Please note that HTTPS is required.

API Credits

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

Testing costs

The report cost depends on the type of report you wish to generate - see the report option in Test Parameters for more info.

Option Cost
A Lighthouse report 1 credits
A PageSpeed and YSlow report 0.7 credits
A Lighthouse, PageSpeed and YSlow report 1.1 credits
A metrics-only report 0.6 credits

Test add-on costs

A PDF render of the report (charged when you request a PDF report resource) +0.2 credits
A full PDF render of the report (charged when you request a full PDF report resource) +0.3 credits
A video of the test load (charged in addition to the test cost if the video parameter is used) +0.9 credits

Report retention costs

Choose your retention period per-report when starting a new test - see the retention option in Test Parameters for more info.

1 month included
6 months +0.4 credits
12 months +0.9 credits
24 months +1.8 credits

API Credit refills

GTmetrix Basic users are given up to 10 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 allowance—credits do not accumulate past your account's Daily API Credit allowance.

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

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.

Authentication

The GTmetrix API uses HTTP Basic Access Authentication as its authentication mechanism. Use your API key as the username and leave the password blank.

We recommend using your HTTP client's built-in basic authentication handling, like in the cURL example 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.

All the API endpoints described below require authentication.

You can generate and view your API key at the top of this page, or go to Account Settings to (re)generate your API key and review API credit usage.

cURL example

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/status

Possible authentication errors

HTTP status Error code Error message
401 E40100 Invalid API key
403 E40300 E-mail address not validated (Your account e-mail address must be validated to use the API)

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 response bodies return a JSON-encoded string. The GTmetrix API uses the JSON:API v1.0 convention for all of its responses and certain requests. See the documentation below for the structure of the data.

Error Format

Errors are returned in the following JSON:API format: 

HTTP/1.1 405 Method Not Allowed

{
  "errors": [
    {
      "status": "405",
      "code": "E40500",
      "title": "HTTP method not allowed",
      "detail": "Method is not supported by the endpoint"
    },
    { ... }
  ]
}

Error Properties

Field Description
status The HTTP code supplied with this error response
code An internal error code associated with this error
title A brief error description
description A detailed error description (only present in certain error cases)

Common Errors

Possible errors that may occur in response to any of the documented requests

HTTP status Error code Error message
400 E40000 Unknown request
405 E40500 HTTP method not allowed
429 E42901 Rate limit exceeded
500 E50000 Internal Server Error
502 E50200 Application server temporarily unavailable
503 E50300 Application server temporarily unavailable

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}
Parameter Description
request-quota The total amount of requests allowed before rate-limiting within the time window
240 requests for GTmetrix Basic, 960 for most GTmetrix PRO users
time-window The size of the request rate-limiting window (60s)
requests-remaining The amount of requests remaining before rate-limiting within the current window
time-remaining Seconds remaining until the end of the current window

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

HTTP status Error code Error message
429 E42901 Rate limit exceeded

REST Requests

Start a Test

POST /api/2.0/tests
Content-Type: application/vnd.api+json

Start a new page test with desired test parameters.

Note that you can only run 2 tests concurrently on a Basic account (GTmetrix PRO users get 8 concurrency) and when you exceed this limit, you will get a 429 HTTP status code. You will need to wait until one of the existing jobs completes, or retry until you get a non 429 status.

Request Object

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    -X POST -H Content-Type:application/vnd.api+json \
    https://gtmetrix.com/api/2.0/tests \
    -d '
{
  "data": {
    "type": "test",
    "attributes": {
      "url":      "https://www.gtmetrix.com",
      "location": "{location_id}",
      "browser":  "{browser_id}",
      "adblock":  1
      ...
    }
  }
}'

Note that the request must be done with the correct Content-Type header, otherwise the API will respond with a 415 error (see a list of errors below).

Test Parameters

Supply your desired test parameters as properties in the attributes object.

Note that not all options may be available to your current plan (see the table footnote).

Property Description Type Required Default
url The URL of the page to test string Yes
location Location ID string No 1
browser Browser ID string No 3
report

Report type:

  • lighthouse for Lighthouse
  • legacy for PageSpeed/YSlow
  • lighthouse,legacy for both
  • none for a metrics-only report
This parameter will vary in credit costs. 		string No lighthouse
retention Choose how long the report will be retained and accessible.

Valid values (in months):
1 (default), 6, 12, 24

This parameter may incur additional credit costs. 		integer No 1
httpauth_username Username for the test page HTTP access authentication

Note this is not API authentication. 		string No
httpauth_password Password for the test page HTTP access authentication

Note this is not API authentication. 		string No
adblock Enable AdBlock integer (0, 1) No 0
cookies Specify cookies to supply with test page requests (Learn more). Array of strings (cookie) No
video Enable generation of video

This parameter incurs additional credit costs. 		integer (0, 1) No 0
stop_onload Stop the test at window.onload instead of after the page has fully loaded (ie. 2 seconds of network inactivity). integer (0, 1) No 0
throttle Throttle the connection. Speed measured in Kbps, latency in ms. See Connection Throttling reference section for sample values. string (down/up/latency) No
allow_url Only load resources that match one of the URLs on this list. This uses the same syntax as the web front end. Array of strings (URL) No
block_url Prevent loading of resources that match one of the URLs on this list. This occurs after the Only Allow URLs are applied. This uses the same syntax as the web front end. Array of strings (URL) No
dns* Use a custom DNS host and IP to run the test with. Array of strings (host:ip_address) No
simulate_device* Simulate the display of your site on a variety of devices using a pre-selected combination of Screen Resolutions, User Agents, and Device Pixel Ratios. See Simulated Devices reference section for sample ID values. string (device id) No
user_agent* Use a custom User Agent string

simulate_device overrides this parameter with preset values. 		string No
browser_width* Set the width of the viewport for the analysis. Also requires browser_height to be set.

simulate_device overrides this parameter with preset values. 		integer (pixels) No 1366
browser_height* Set the height of the viewport for the analysis. Also requires browser_width to be set.

simulate_device overrides this parameter with preset values. 		integer (pixels) No 768
browser_dppx* Set the device pixel ratio for the analysis. Decimals are allowed.

simulate_device overrides this parameter with preset values. 		number (1 - 5) No 1
browser_rotate* Swaps the width and height of the viewport for the analysis. integer (0, 1) No 0

* These parameters are only available with GTmetrix PRO plans. Learn more.

Successful Response

The test was successfully queued

HTTP/1.1 202 Accepted
Location: /api/2.0/tests/{test_id}

{
  "data": {
    "type": "test",
    "id":   "{test_id}",
    "attributes": {
      "source":   "api",
      "location": "{location_id}",
      "browser":  "{browser_id}",
      "state":    "queued",
      "created":  1617680457,
    }
  },
  "meta": {
    "credits_left": 121.2,
    "credits_used": 2.8
  },
  "links": {
    "self": "/api/2.0/tests/{test_id}"
  }
}
Property Description Type
data A new Test resource showing its current state object
meta.credits_left The new account API credit total number
meta.credits_used Credits charged for starting this test number
links.self A URL to poll the test state string

The Location header always points to the same URL as links.self.

Possible errors

HTTP status Error code Error message
400 E40002 Request body syntax error
400 E40003 Invalid parameter (The selected browser is not available via the API)
400 E40004 Invalid parameter:
  Invalid report type selected,
  The selected browser does not support the selected report type,
  Invalid retention option selected or
  Various other errors relating to the Test Parameters
402 E40201 Insufficient API credits for this request
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)
429 E42900 Too many tests pending (Please retry after your existing tests have completed)

Get a list of tests

GET /api/2.0/tests

Get a paginated list of all the tests belonging to your account.

Note that the tests are only retained for 24 hours. The GTmetrix report for the URL will be retained for 1 month .

See also: Start a test

URI query parameters

You can choose to augment the returned test list by using the following query parameters in this request's URL. Consult the Test attribute list below for more information on attributes these parameters reference.

Parameter Description Example
sort Sort the list by test attribute.

Supported test attributes: created, started, finished
Prepend the attribute with '-' for descending sort
Defaults to created (ascending)
Use comma separated, or pass the parameter multiple times for multiple sorting 		?sort=created
?sort=-started&sort=created
?sort=created,finished
filter Filter the list by test attribute value.

Supported test attributes: state, created, started, finished, browser, location
Supported numeric operators (append to attribute name): :eq, :lt, :lte, :gt, :gte
Multiple values allowed (filters will use an AND boolean match) 		?filter[state]=completed
?filter[finished:gt]=1617680457
page Pagination settings for the result list.

Use page[size] to set the page size (default 50, max 500)
Use page[number] to set the page 		?page[number]=4

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/tests

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "test",
      "id":   "{test_id}",
      "attributes": {
        "source":   "api",
        "location": "{location_id}",
        "browser":  "{browser_id}",
        "state":    "completed",
        "created":  1617680457,
        "started":  1617680459,
        "finished": 1617680502
      },
      "links": {
        "report": "https://gtmetrix.com/api/2.0/reports/{report_id}"
      }
    },
    { ... },
    ...
    { ... }
  ],
  "links": {
    "prev":  "/api/2.0/tests?sort=created&page[number]=2",
    "next":  "/api/2.0/tests?sort=created&page[number]=4",
  }
}
Property Description Type
data A paginated array of Tests array of objects
links.* Pagination links to navigate the result pages (see page query parameter above for more details) string

Possible errors

HTTP status Error code Error message
400 E40005 Invalid query parameter
400 E40006 Invalid query parameter (unknown filter value)
400 E40007 Invalid query parameter (invalid sort parameter value)
400 E40008 Invalid query parameter (invalid page[size] or page[number] value)

Get a test

GET /api/2.0/tests/{test_id}

Provides the current state of a started test. The recommended poll interval is 3 seconds.

Note that the tests are only retained for 24 hours.

See also: Start a test

URI values

Parameter Description Type
test_id The test ID string

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/tests/{test_id}

The test is still running and not yet complete:

HTTP/1.1 200 OK
Retry-After: 3

The test is complete:

HTTP/1.1 303 See Other
Location: /api/2.0/reports/{report_id}

If the test is complete, the API responds with a redirect to the Report result.

Response body

In both the above cases, the response body has the following structure 
{
  "data": {
    "type": "test",
    "id":   "{test_id}",
    "attributes": {
      "source":   "api",
      "location": "{location_id}",
      "browser":  "{browser_id}",
      "state":    "completed",
      "created":  1617680457,
      "started":  1617680459,
      "finished": 1617680502
    },
    "links": {
        "report": "https://gtmetrix.com/api/2.0/reports/{report_id}"
    }
  }
}
Should the test fail for any reason, the response body will contain more details about the error, such as the example below 
HTTP/1.1 200 OK

{
  "data": {
    "type": "test",
    "id":   "{test_id}",
    "attributes": {
      "source":   "api",
      "location": "{location_id}",
      "browser":  "{browser_id}",
      "created":  1629829789,
      "state":    "error",
      "error":    "The page returned an error: 404 Not Found",
      "started":  1629829789,
      "finished": 1629829794
    }
  }
}
Property Description Type
data A single Test resource object

Test Resource

Property Description Type
data.type The resource type. Always has the value "test" string
data.id The test ID string
data.attributes.state Current test state (queued, started, error or completed) string
data.attributes.error Error description (present only if state is "error") string
data.attributes.browser The Browser ID used for this test string
data.attributes.location The Location ID used for this test string
data.attributes.source The source of this test - currently only has the value "api" string
data.attributes.created Time when the test was created integer (unix timestamp)
data.attributes.started Time when the test was started integer (unix timestamp)
data.attributes.finished Time when the test was finished (present only if state is "completed" or "error") integer (unix timestamp)
data.links.report URL of the Report (present only if the test state is "complete") string

Possible errors

HTTP status Error code Error message
404 E40400 Test not found

Get a report

GET /api/2.0/reports/{report_id}

Retrieve the report data. Reports are the result of a completed test and contain page load information.

GTmetrix reports will be retained for 1 month.

URI values

Parameter Description Type
report_id The report ID identifying the report string

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/reports/{report_id}

HTTP/1.1 200 OK
Cache-Control: max-age=31536000

{
  "data": {
    "type": "report",
    "id":   "{report_id}",
    "attributes": {
      "gtmetrix_grade":    "A",
      "performance_score": 94,
      "structure_score":   99,
      ...
    },
    "links": {
      "har": "/api/2.0/reports/{report_id}/resources/har",
      ...
    }
  }
}
Property Description Type Report
data.type The resource type. Always has the value "report" string
data.id The report ID string
data.attributes.browser The Browser ID used for this report string
data.attributes.location The Location ID used for this report string
data.attributes.source The source of this report - currently only has the value "api" string
data.attributes.gtmetrix_grade GTmetrix letter grade (A-F) string Lighthouse
data.attributes.performance_score GTmetrix performance score integer Lighthouse
data.attributes.structure_score GTmetrix structure score integer Lighthouse
data.attributes.pagespeed_score PageSpeed score integer Legacy
data.attributes.yslow_score YSlow score integer Legacy
data.attributes.html_bytes The HTML size (may be the compressed size) integer
data.attributes.page_bytes The total page size integer
data.attributes.page_requests The total number of requests made to fetch the entire page integer
data.attributes.redirect_duration Time spent redirecting (in milliseconds) integer
data.attributes.connect_duration Connection time for the html page request (in milliseconds). This timing is a sum of blocked, DNS, connect and send times and may be 0 if the request was redirected. integer
data.attributes.backend_duration Backend or wait time for the html page request (in milliseconds) integer
data.attributes.time_to_first_byte TTFB (in milliseconds) integer
data.attributes.first_paint_time First paint time (in milliseconds) integer
data.attributes.first_contentful_paint First contentful paint time (in milliseconds) integer
data.attributes.dom_interactive_time DOM interactive time (in milliseconds) integer
data.attributes.dom_content_loaded_time DOM content loaded time (in milliseconds) integer
data.attributes.dom_content_loaded_duration DOM content loaded duration (in milliseconds). The duration of which the DOMContentLoaded event JavaScript takes to complete. integer
data.attributes.onload_time Window.onload time (in milliseconds); same as results.page_load_time integer
data.attributes.onload_duration Window.onload duration (in milliseconds). The duration of which the window.onload event JavaScript takes to complete. integer
data.attributes.fully_loaded_time Fully loaded time (in milliseconds). If the stop-onload option is used, then this value will be set to -1.
Learn more 		integer
data.attributes.rum_speed_index RUM Speed Index integer
data.attributes.speed_index Speed Index integer Lighthouse
data.attributes.largest_contentful_paint Largest contentful paint time (in milliseconds) integer Lighthouse
data.attributes.time_to_interactive Time to interactive (in milliseconds) integer Lighthouse
data.attributes.total_blocking_time Total blocking time (in milliseconds) integer Lighthouse
data.attributes.cumulative_layout_shift Cumulative layout shift number Lighthouse
data.links.* Contains URLs to Report Resources string
data.links.har URL to the HAR file resource string
data.links.video URL to the page load video in mp4 format (present if the test was run with a video option) string
data.links.report_pdf URL to generate a report PDF

This request will incur additional credit costs. 		string
data.links.report_pdf_full URL to generate a full report PDF

This request will incur additional credit costs. 		string
data.links.report_url URL to the GTmetrix report page string
data.links.screenshot URL to the report screenshot image string
data.links.optimized_images URL to a tar archive of optimized image assets

Only available for 24 hours after report was generated. 		string Lighthouse
data.links.lighthouse URL to the Lighthouse report in JSON format string Lighthouse
data.links.pagespeed URL to the PageSpeed report in JSON format string Legacy
data.links.pagespeed_files URL to the PageSpeed files tar archive

Only available for 24 hours after report was generated. 		string Legacy
data.links.yslow URL to the YSlow report in JSON format string Legacy

Possible errors

HTTP status Error code Error message
404 E40401 Report not found

Delete a report

DELETE /api/2.0/reports/{report_id}

Delete a report and all of its resources.

URI values

Parameter Description Type
report_id The report ID identifying the report string

Successful Response

Report has been successfully deleted

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: -X DELETE \
    https://gtmetrix.com/api/2.0/reports/{report_id}

HTTP/1.1 200 OK

{
  "data": {
    "type": "report",
    "id":   "{report_id}"
  }
}

Possible errors

HTTP status Error code Error message
404 E40401 Report not found

Retest a report

POST /api/2.0/reports/{report_id}/retest

Retest a report with the same page settings. This is semantically identical to starting a new test using the same parameters as the test that generated this report.

URI values

Parameter Description Type
report_id The report ID identifying the report string

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: -X POST \
    https://gtmetrix.com/api/2.0/reports/{report_id}/retest

HTTP/1.1 202 Accepted
Location: /api/2.0/tests/{test_id}

...

The response is identical to starting a new test.

Possible errors

HTTP status Error code Error message
404 E40402 Page not found

Get a report resource

GET /api/2.0/reports/{report_id}/resources/{resource_name}

Get a report resource.

Note that these resource URLs are not public URLs (they still require API authentication), so if you want to make them available to your users, you should download them locally.

URI values

Parameter Description Type
report_id The report ID identifying the report string
resource_name The desired report resource name (see options below) string

Resources

The resources available to fetch from a report

Resource Name Description Report
screenshot.jpg Download the screenshot
net.har 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.
video.mp4 URL to the page load video in mp4 format (available if the test was run with a video option)
optimized-images.tar Download optimized image assets as a tar archive.

Only available for 24 hours after report was generated. 		Lighthouse
report.pdf Download the GTmetrix report in PDF format.
Append the "?full=1" query to get a full PDF version of the report.
This request may result in a 302 redirect if the PDF generation time is long. Ensure your HTTP client follows the redirect.

This request incurs additional credit costs.
lighthouse.json Download the Lighthouse report in JSON format Lighthouse
pagespeed.json Download the PageSpeed report in JSON format Legacy
pagespeed-files.tar Download the PageSpeed files as a tar archive

Only available for 24 hours after report was generated. 		Legacy
yslow.json Download the YSlow report in JSON format Legacy

cURL example

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/reports/{report_id}/resource/net.har

HTTP/1.1 200 OK
Cache-Control: max-age=31536000
Content-Type: application/json

...

Possible errors

HTTP status Error code Error message Resource
400 E40001 Invalid resource request
404 E40401 Report not found
404 E40405 Screenshot not found screenshot.jpg
404 E40406 HAR not found net.har
402 E40201 Insufficient API credits for this request report.pdf
403 E40301 Your plan does not have access to report PDF generation report.pdf
403 E40302 Your plan does not have access to full report PDF generation report.pdf
404 E40407 PDF unavailable report.pdf
500 E50001 Error generating the report PDF report.pdf
404 E40407 Video not found video.mp4
416 E41600 Video Range header syntax error video.mp4
404 E40410 Lighthouse report JSON unavailable lighthouse.json
500 E50002 Error generating Lighthouse report JSON lighthouse.json
404 E40411 Lighthouse optimized images unavailable optimized-images.tar
404 E40412 Lighthouse optimized images unavailable (Optimized images have expired) optimized-images.tar
404 E40413 PageSpeed report JSON unavailable pagespeed.json
404 E40414 YSlow report JSON unavailable yslow.json
404 E40415 PageSpeed optimized files unavailable pagespeed-files.tar
404 E40416 PageSpeed optimized files unavailable (PageSpeed optimized files have expired) pagespeed-files.tar

Get a list of available test locations

GET /api/2.0/locations

This list is limited to the test locations currently available to you. Visit the Locations Page for more information on Basic and Premium test locations.

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/locations

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "location",
      "id":   "{location_id}",
      "attributes": {
        "name":     "Sydney, Australia",
        "default":  false,
        "browsers": [ "1", "3" ]
      }
    },
    { ... },
    ...
    { ... }
  ]
}
Property Description Type
data A list of Locations array of objects

Get location details

GET /api/2.0/locations/{location_id}

Get details of a location by ID

Note that you can only retrieve details about locations available to you. Visit the Locations Page for more information on Basic and Premium test locations.

URI values

Parameter Description Type
location_id The location ID string

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/locations/{location_id}

HTTP/1.1 200 OK

{
  "data": {
    "type": "location",
    "id":   "{location_id}",
    "attributes": {
      "name":     "Hong Kong, China",
      "default":  false,
      "browsers": [ "{browser_id}", ... ]
    }
  }
}
Property Description Type
data A Location object

Location Resource

Property Description Type
type The resource type. Always has the value "location" string
id The location ID string
attributes.name The location name string
attributes.default Whether this is the default location boolean
attributes.browsers List of Browser IDs supported by this location array of strings

Possible errors

HTTP status Error code Error message
404 E40404 Location not found

Get a list of available browsers

GET /api/2.0/browsers

This list is limited to the test browsers currently available to you.

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/browsers

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "browser",
      "id":   "browser_id",
      "attributes": {
        "name":       "Chrome (Desktop)",
        "default":    true,
        "platform":   "desktop",
        "adblock":    true,
        "cookies":    true,
        "dns":        true,
        "filtering":  true,
        "http_auth":  true,
        "resolution": true,
        "throttle":   true,
        "user_agent": true,
        "video":      true,
        "lighthouse": true,
        "device":     ""
      }
    },
    { ... },
    ...
    { ... }
  ]
}
Property Description Type
data A list of Browsers array of objects

Get browser details

GET /api/2.0/browsers/{browser_id}

Get details about a browser by browser ID. This list is limited to the test browsers currently available to you.

URI values

Parameter Description Type
browser_id The browser ID string

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/browsers/{browser_id}

HTTP/1.1 200 OK

{
  "data": {
    "type": "browser",
    "id":   "{browser_id}",
    "attributes": {
      "name":       "Chrome (Desktop)",
      "default":    true,
      "platform":   "desktop",
      "adblock":    true,
      "cookies":    true,
      "dns":        true,
      "filtering":  true,
      "http_auth":  true,
      "resolution": true,
      "throttle":   true,
      "user_agent": true,
      "video":      true,
      "lighthouse": true,
      "device":     ""
    }
  }
}
Parameter Description Type
data A Browser integer

Browser Resource

Property Description Type
type The resource type. Always has the value "browser" string
id The browser ID string
attributes.name The browser display name string
attributes.browser The browser short name string
attributes.platform The browser platform (desktop/android) string
attributes.device The browser device type (phone/tablet); if applicable string
attributes.adblock Whether this browser supports AdBlock boolean
attributes.lighthouse Whether this browser supports Lighthouse (non-legacy) testing boolean
attributes.cookies Whether this browser supports specifying cookies boolean
attributes.filtering Whether this browser supports URL filtering boolean
attributes.http_auth Whether this browser supports HTTP authentication boolean
attributes.throttle Whether this browser supports connection throttling boolean
attributes.video Whether this browser supports video generation boolean
attributes.dns Whether this browser supports custom DNS boolean
attributes.user_agent Whether this browser supports setting a custom User Agent boolean
attributes.resolution Whether this browser supports setting a custom viewport resolution and device pixel ratio boolean

Possible errors

HTTP status Error code Error message
404 E40403 Browser not found

Get your account status

GET /api/2.0/status
Get the current account details

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/status

HTTP/1.1 200 OK

{
  "data": {
    "type": "user",
    "id":   "e8ddc55d93eb0e8281b255ea236dcc4f",
    "attributes": {
      "api_credits": 1497,
      "api_refill":  1618437519
    }
  }
}
Properties Description Type
data.type The resource type. Always has the value "user" string
data.id Your API key string
data.attributes.api_credits Current API credit balance number
data.attributes.api_refill Unix timestamp for next API refill number

Reference Values

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

List of Simulated Devices

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

Device type Device ID Device full name Screen resolution
phones
iphone_x Apple iPhone X/XS/11/12/12 mini/12 Pro 375x812 @ 3 DPR
iphone_xr Apple iPhone XR 414x896 @ 2 DPR
iphone_xs_max Apple iPhone XS Max/11 Pro/11 Pro Max/12 Pro Max 414x896 @ 3 DPR
iphone_4s Apple iPhone 4/4S 320x480 @ 2 DPR
iphone_se Apple iPhone 5/5C/5S/SE (1st Gen) 320x568 @ 2 DPR
iphone_7_plus Apple iPhone 6/6S/7/8 Plus 414x736 @ 3 DPR
iphone_7 Apple iPhone 6/6S/7/8/SE (2nd Gen) 375x667 @ 2 DPR
nexus_4 Google Nexus 4 384x640 @ 2 DPR
nexus_5 Google Nexus 5 360x640 @ 3 DPR
pixel Google Nexus 5X/Pixel/Pixel 2 412x732 @ 2.625 DPR
pixel_xl Google Nexus 6/6P/Pixel XL/Pixel 2 XL 412x732 @ 3.5 DPR
pixel_3 Google Pixel 3 412x824 @ 2.625 DPR
pixel_3_xl Google Pixel 3 XL/3a XL 412x847 @ 3.5 DPR
pixel_4 Google Pixel 3a/4/4 XL 412x869 @ 2.625 DPR
pixel_4a Google Pixel 4a/5 412x892 @ 2.625 DPR
lumia_520 Nokia Lumia 520 320x533 @ 1.5 DPR
galaxy_note_3 Samsung Galaxy Note 3 360x640 @ 3 DPR
galaxy_note_5 Samsung Galaxy Note 4/5 412x732 @ 2.625 DPR
galaxy_note_8 Samsung Galaxy Note 8/9 412x846 @ 2.625 DPR
galaxy_note_10 Samsung Galaxy Note 10/10+ 412x869 @ 2.625 DPR
galaxy_note_20 Samsung Galaxy Note 20/20 Ultra 412x915 @ 2.625 DPR
galaxy_s5 Samsung Galaxy S4/S5 360x640 @ 3 DPR
galaxy_s7 Samsung Galaxy S6/S7 360x640 @ 4 DPR
galaxy_s8 Samsung Galaxy S8/S8+/S9/S9+ 360x740 @ 3 DPR
galaxy_s10 Samsung Galaxy S10/S10+ 360x760 @ 3 DPR
galaxy_s20 Samsung Galaxy S20/S20+/S20 Ultra 360x800 @ 3 DPR
tablets
ipad_2 Apple iPad 2/Mini 1024x768 @ 1 DPR
ipad Apple iPad 3/4/Air/Air 2/2017 1024x768 @ 2 DPR
nexus_7 Google Nexus 7 960x600 @ 2 DPR
nexus_10 Google Nexus 10 1280x800 @ 2 DPR
galaxy_tab_a Samsung Galaxy Tab A 10.1 960x600 @ 2 DPR
galaxy_tab_s3 Samsung Galaxy Tab S3 1024x768 @ 2 DPR
galaxy_tab_s7 Samsung Galaxy Tab S7/S7+ 1280x800 @ 2 DPR
galaxy_tab_4 Samsung Galaxy Tab 4 1280x800 @ 1 DPR

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.

Connection Full Name Connection String ID
Broadband Fast (20/5 Mbps, 25ms) 20000/5000/25
Broadband (5/1 Mbps, 30ms) 5000/1000/30
Broadband Slow (1.5 Mbps/384 Kbps, 50ms) 1500/384/50
LTE Mobile (15/10 Mbps, 100ms) 15000/10000/100
3G Mobile (1.6 Mbps/768 Kbps, 200ms) 1600/768/200
2G Mobile (240/200 Kbps, 400ms) 240/200/400
56K Dial-up (50/30 Kbps, 125ms) 50/30/125

Lighthouse Report JSON

The lighthouse.json resource is an extended Lighthouse report in JSON format. It is fully compatible with the Lighthouse Report Viewer and other Lighthouse tools.

It also provides additional data that drives the report presentation in our web interface. All of our extended data have keys prepended with an underscore (_) and is described below.

Name Description
_structureScore

The Structure Score uses Lighthouse and custom GTmetrix audits to assess how well your page is built for optimal performance.

The score is a value between 0 and 1, where 0 = 0% and 1 = 100%.

_structureScore is available as an overall score as well as to most audits, except diagnostic/informative type audits.

_impactScore

An estimation of the impact the audit has on your page performance.

The score is a value between 0 and 1, where 0 = "No Impact" and 1 = "High Impact".

_impactScore is available to most audits, except diagnostic/informative type audits, which will have a null value.

Impact to Score breakdown:

  • None = 0
  • Low ≤ 0.12
  • Med-Low ≤ 0.24
  • Med ≤ 0.36
  • Med-High ≤ 0.48
  • High ≤ 1
_gtmetrixScore

A proprietary combined score of the Performance and Structure scores meant to reflect how fast your page performs (in terms of loading, interactivity and visual stability), and how well it's built for performance.

The score is a value between 0 and 1, where 0 = 0% and 1 = 100%.

_gtmetrixScore is only available as an overall score, as it applies to the entire page.

Letter Grade to Score breakdown:

  • A ≥ 0.9
  • B ≥ 0.8
  • C ≥ 0.7
  • D ≥ 0.6
  • E ≥ 0.5
  • F < 0.5

Changelog

September 22nd, 2021

  • Fix "Start a test" response credits documentation details to be numbers not integers
  • Add more details to filter and sort documentation for "Get a list of tests"
  • Add more details to Lighthouse Report JSON extended data
  • OpenAPI spec: renamed report_slug parameter to report_id for consistency

July 13th, 2021

  • Fix Start test parameters: cookies, allow_url, block_url, dns to be array of strings
  • OpenAPI spec: fix parameters that should be arrays of strings: cookies, allow_url, block_url, dns
  • OpenAPI spec: add missing retention parameter
  • OpenAPI spec: fix type of browser_dppx to be "number" not "integer"

May 3rd, 2021

  • GTmetrix API v2.0 launched