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:
|
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/statusGet 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:
|
_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:
|
Changelog
September 22nd, 2021
- Fix "Start a test" response credits documentation details to be
number
s notinteger
s - 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 toreport_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