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.
Additionally, you can also fetch non-API generated reports, tests and pages, such as done via on-demand or monitoring.
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 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 allowance—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.
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.
Note that if you are accessing the API using an API key generated from a GTmetrix Team plan with a role of Viewer, you will not be able to generate tests, delete reports/pages or create PDF reports.
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) |
403 | E40301 | Your role does not have access to this feature. Contact your team administrator for more info |
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 | |
anonymize_user_agent |
Strips the trailing "GTmetrix" tag from the User Agent, resulting in the browser's default User Agent. This option is not available for PRO users, use the user_agent option below for full customization instead.
|
integer (0, 1) | No | 0 |
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 by default unless higher report retention was specified when generating the test.
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) . For multiple sorting use comma separated values, or pass the parameter multiple times. |
?sort=created ?sort=-started&sort=created ?sort=created,finished |
filter |
Filter the list by test attribute value. By default, only tests with attribute source = api will be returned. Can be overriden. Supported test attributes: state, source, created, started, finished, browser, location. Supported numeric operators (append to attribute name): :eq (equals), :lt (less than), :lte (less than equals), :gt (greater than), :gte (greater than equals). Multiple values allowed for the same filter name You can also use the special filter name :bool to specify the boolean connector between each filters. Allowed values: AND (default), OR
|
?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": { "report": "{report_id}", "url": "https://gtmetrix.com", "page": "{page_id}", "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}", "location": "https://gtmetrix.com/api/2.0/locations/{location_id}", "browser": "https://gtmetrix.com/api/2.0/browsers/{browser_id}" } }, { ... }, ... { ... } ], "links": { "prev": "/api/2.0/tests?sort=created&page[number]=2", "next": "/api/2.0/tests?sort=created&page[number]=4", }, "meta": { "curr_page": 3 } }
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 |
meta.curr_page | The current page from pagination (see page) | 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 303 redirect to the Report result.
Clients are encouraged to follow the redirect given the status code and location
header, or otherwise parse the response object when the test is complete.
Response body
In both the above cases, the response body has the following structure (with attributes being populated as the test completes){ "data": { "type": "test", "id": "{test_id}", "attributes": { "report": "{report_id}", "url": "https://gtmetrix.com", "page": "{page_id}", "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}", "location": "https://gtmetrix.com/api/2.0/locations/{location_id}", "browser": "https://gtmetrix.com/api/2.0/browsers/{browser_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": { "url": "https://gtmetrix.com", "page": "{page_id}", "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.report | ID of the Report generated (preset only if state is "completed") | string |
data.attributes.url | The URL of the page tested | string |
data.attributes.page | ID of the page associated with this test | 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 (api, on-demand or monitored) | 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 |
data.links.location | URL of the Location used | string |
data.links.browser | URL of the Browser used | 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 API-generated reports will be retained for 1 month by default, see Start a test for more retention options.
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": { "url": "https://gtmetrix.com", "page": "{page_id}", "test": "{test_id}", "source": "api", "created": 1660868227, "expires": 1676420227, "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.url | The URL of the page tested | string | |
data.attributes.page | ID of the page associated with this report | string | |
data.attributes.test | ID of the test that generated this report (if still available) | string | |
data.attributes.source | The source of this report - can be "api", "on-demand" or "monitored" | string | |
data.attributes.created | Time when the report was created | integer (unix timestamp) | |
data.attributes.expires |
Time when the report will expire. Report expiration is based on your GTmetrix plan's report retention or specified retention for API generated reports. API generated reports have default retention of 1 month, or you can specify a different duration. See Test Parameters. |
integer (unix timestamp) | |
data.attributes.browser | The Browser ID used for this report | string | |
data.attributes.location | The Location ID used for this report | 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.analysis_options | URL to the analysis options object used to generate this report | 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.filmstrip | URL to the filmstrip images (JSON encoded) captured during page load. Append "base64=1" query parameter to get base64 encoded string jpeg data for each screenshot. See Filmstrip Data for more info. | string | Lighthouse |
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
This operation will permanently delete Report data and cannot be undone — proceed with caution.
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, as well as retest a page endpoint.
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. The Link Attribute Name correspond to links returned in Report object data.links section.
Resource Endpoint Name | Link Attribute Name | Description | Report |
---|---|---|---|
screenshot.jpg | screenshot |
Download the Report screenshot | |
filmstrip.json | filmstrip |
URL to the filmstrip images (JSON encoded) captured during page load. Append "base64=1" query parameter to get base64 encoded string jpeg data for each screenshot. See Filmstrip Data for more info. | Lighthouse |
filmstrip-frame.jpg | filmstrip-frame |
Fetch a filmstrip JPEG frame. Expects an id frame query parameter. See Filmstrip Data for more info. |
Lighthouse |
net.har | 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. | |
analysis-options | analysis_options |
Fetch the analysis options used to generate this report. Note that sensitive info (HTTP auth and cookies) are included. See Analysis Options for more info. | |
video.mp4 | video |
URL to the page load video in mp4 format (available if the test was run with a video option) | |
optimized-images.tar | optimized_images |
Download optimized image assets as a tar archive. Only available for 24 hours after report was generated. |
Lighthouse |
report.pdf | 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 | lighthouse |
Download the Lighthouse report in JSON format | Lighthouse |
pagespeed.json | pagespeed |
Download the PageSpeed report in JSON format | Legacy |
pagespeed-files.tar | pagespeed_files |
Download the PageSpeed files as a tar archive Only available for 24 hours after report was generated. |
Legacy |
yslow.json | yslow |
Download the YSlow report in JSON format | Legacy |
cURL example
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \ https://gtmetrix.com/api/2.0/reports/{report_id}/resources/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 |
429 | E42903 | Please wait until current PDF report requests complete or try again in a few moments | 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 | E40409 | Filmstrip unavailable | filmstrip.json |
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 page
GET /api/2.0/pages/{page_id}
Retrieve a specific page data. A page is an aggregation of reports sharing the same URL and analysis options settings.
A new page object is automatically created when a new successful report is created with analysis options that differ from all your previous pages.
Conversely, the same page id is used when a test is created using the same URL and analysis options combination as before.
GTmetrix will keep the page data so long as it has at least one valid report in it, see Get a report for more information about reports.
URI values
Parameter | Description | Type |
---|---|---|
page_id | The page ID identifying the page | string |
Successful Response
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \ https://gtmetrix.com/api/2.0/pages/{page_id} HTTP/1.1 200 OK { "data": { "type": "page", "id": "{page_id}", "attributes": { "url": "https://gtmetrix.com/", "created": 1651537199, "browser": "{browser_id}", "location": "{location_id}", "latest_report_time": 1663780062, "latest_report": "{report_id}", "report_count": 5, "monitored": "no" }, "links": { "retest": "https://gtmetrix.com/api/2.0/pages/{page_id}/retest", "latest_report": "https://gtmetrix.com/api/2.0/pages/{page_id}/latest-report", "reports": "https://gtmetrix.com/api/2.0/pages/{page_id}/reports", "location": "https://gtmetrix.com/api/2.0/locations/{location_id}", "browser": "https://gtmetrix.com/api/2.0/browsers/{browser_id}" } } }
Property | Description | Type |
---|---|---|
data.type | The resource type. Always has the value "page" | string |
data.id | The page ID | string |
data.attributes.url | The URL of the page tested | string |
data.attributes.browser | The Browser ID set for the analysis options | string |
data.attributes.location | The Location ID set for the analysis options | string |
data.attributes.created | Time when this page was created | integer (unix timestamp) |
data.attributes.latest_report | ID of the latest report generated for this page | string |
data.attributes.latest_report_time | Time when the latest report was generated | integer (unix timestamp) |
data.attributes.report_count | Number of valid reports currently associated with this page | integer |
data.attributes.monitored | Whether this page is monitored - can be "no", "hourly", "daily", "weekly" or "monthly". See how to setup monitoring in GTmetrix | string |
data.links.latest_report |
URL to fetch the latest report of this page. Returns a report object. |
string |
data.links.retest |
URL to generate a new report for this page. This method will reuse the page's analysis options set and is analoogus to retest a report endpoint. requires a POST HTTP method and returns a test object. |
string |
data.links.reports | URL to fetch a list of reports belonging to this page. | string |
data.links.location | URL of the Location used | string |
data.links.browser | URL of the Browser used | string |
Possible errors
HTTP status | Error code | Error message |
---|---|---|
404 | E40402 | Page not found |
Get a list of pages
GET /api/2.0/pages
Get a paginated list of all the pages belonging to your account (similar to GTmetrix Dashboard).
Note that only valid pages are returned - these are pages that have at least one valid report, subject to report data retention.
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 Page attribute list below for more information on attributes these parameters reference.
Parameter | Description | Example |
---|---|---|
sort |
Sort the list by page attribute. Supported page attributes: created or latest_report_time (note that sorting/filtering by report_count is not available at this time). Prepend the attribute with '-' for descending sort Defaults to created (descending) Use comma separated, or pass the parameter multiple times for multiple sorting |
?sort=created ?sort=-latest_report_time&sort=created |
filter |
Filter the list by page attribute value. Supported report attributes: url, monitored, browser, location and any numeric based report attributes from above. Note that url filtering is done through a fuzzy search. Supported numeric operators (append to attribute name): :eq (equals), :lt (less than), :lte (less than equals), :gt (greater than), :gte (greater than equals) Multiple values allowed for the same filter name You can also use the special filter name :bool to specify the boolean connector between each filters. Allowed values: AND (default), OR
|
?filter[url]=gtmetrix ?filter[created:gt]=1617680457 |
page |
Pagination settings for the result list. Use page[size] to set the page size (default 10, max 500) Use page[number] to set the page |
?page[number]=4 |
Successful Response
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \ https://gtmetrix.com/api/2.0/pages HTTP/1.1 200 OK { "data": [ { "data": { "type": "page", "id": "{page_id}", "attributes": { "url": "https://gtmetrix.com/", "created": 1651537199, "browser": "{browser_id}", "location": "{location_id}", "latest_report_time": 1663780062, "latest_report": "{report_id}", "report_count": 5, "monitored": "no" }, "links": { "retest": "https://gtmetrix.com/api/2.0/pages/{page_id}/retest", "latest_report": "https://gtmetrix.com/api/2.0/pages/{page_id}/latest-report", "reports": "https://gtmetrix.com/api/2.0/pages/{page_id}/reports", "location": "https://gtmetrix.com/api/2.0/locations/{location_id}", "browser": "https://gtmetrix.com/api/2.0/browsers/{browser_id}" } } }, { ... }, ... { ... } ], "links": { "prev": "/api/2.0/pages?page[number]=2", "next": "/api/2.0/pages?page[number]=4", }, "meta": { "curr_page": 3 } }
Property | Description | Type |
---|---|---|
data | A paginated array of pages | array of objects |
links.* | Pagination links to navigate the result pages (see page query parameter above for more details) | string |
meta.curr_page | The current page from pagination (see page) | 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) |
Delete a page
This operation will permanently delete Report data and cannot be undone — proceed with caution.
DELETE /api/2.0/pages/{page_id}
Delete a page. This will delete all of the reports and associated history for this page.
URI values
Parameter | Description | Type |
---|---|---|
page_id | The page ID identifying the page | string |
Successful Response
Page has been successfully deleted.
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: -X DELETE \ https://gtmetrix.com/api/2.0/pages/{page_id} HTTP/1.1 200 OK { "data": { "type": "page", "id": "{page_id}" } }
Possible errors
HTTP status | Error code | Error message |
---|---|---|
404 | E40402 | Page not found |
Retest a page
POST /api/2.0/pages/{page_id}/retest
Retest a page, reusing the same page settings. This is semantically identical to starting a new test using the same parameters of the last test to generate a report on this page, as well as retest a report endpoint.
URI values
Parameter | Description | Type |
---|---|---|
page_id | The page ID identifying the page | string |
Successful Response
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: -X POST \ https://gtmetrix.com/api/2.0/pages/{page_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 | E40404 | Page not found |
Get the latest report from a page
GET /api/2.0/pages/{page_id}/latest-report
Fetches the latest report from a specific page.
URI values
Parameter | Description | Type |
---|---|---|
page_id | The page ID identifying the page | string |
Successful Response
Same response as get a report.
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \ https://gtmetrix.com/api/2.0/pages/{page_id}/latest-report HTTP/1.1 200 OK Cache-Control: max-age=31536000 { "data": { "type": "report", "id": "{report_id}", "attributes": { "url": "https://gtmetrix.com", "page": "{page_id}", "test": "{test_id}", "source": "api", "created": 1660868227, "expires": 1676420227, "gtmetrix_grade": "A", "performance_score": 94, "structure_score": 99, ... }, "links": { "har": "/api/2.0/reports/{report_id}/resources/har", ... } } }
Possible errors
HTTP status | Error code | Error message |
---|---|---|
404 | E40404 | Page not found |
Get a list of reports from a page
GET /api/2.0/pages/{page_id}/reports
Get a paginated list of all the reports belonging to a page.
Note that only valid reports are returned - retention of your API-generated reports depend on the retention value supplied (default of 1 month). Other reports' retention period (on-demand or monitored) depend on your account's data retention for reports.
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 Report attribute list below for more information on attributes these parameters reference.
Note that searching reports with a filter and/or sorting parameter(s) are expensive operations, therefore GTmetrix only allows making one of these requests at a time.
Parameter | Description | Example |
---|---|---|
sort |
Sort the list by report attribute. Supported report attributes: created, expires, performance_score, structure_score and any numeric based report attribute. Prepend the attribute with '-' for descending sort Defaults to created (descending). Use comma separated, or pass the parameter multiple times for multiple sorting |
?sort=created ?sort=-performance_score&sort=created ?sort=structure_score,expires |
filter |
Filter the list by report attribute value. Supported report attributes: source, gtmetrix_grade, started, finished, browser, location and any numeric based report attribute. Supported numeric operators (append to attribute name): :eq (equals), :lt (less than), :lte (less than equals), :gt (greater than), :gte (greater than equals). Multiple values allowed for the same filter name. You can also use the special filter name :bool to specify the boolean connector between each filters. Allowed values: AND (default), OR
|
?filter[source]=on-demand ?filter[created: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/pages/{page_id}/reports HTTP/1.1 200 OK { "data": [ { "type": "report", "id": "{report_id}", "attributes": { "url": "https://gtmetrix.com", "page": "{page_id}", "created": 1660868227, "expires": 1676420227, "source": "api", "gtmetrix_grade": "A", "performance_score": 94, "structure_score": 99, ... }, "links": { "har": "/api/2.0/reports/{report_id}/resources/har", ... } }, { ... }, ... { ... } ], "links": { "prev": "/api/2.0/reports?sort=created&page[number]=2", "next": "/api/2.0/reports?sort=created&page[number]=4", }, "meta": { "curr_page": 3 } }
Property | Description | Type |
---|---|---|
data | A paginated array of Reports | array of objects |
links.* | Pagination links to navigate the result pages (see page query parameter above for more details) | string |
meta.curr_page | The current page from pagination (see page) | 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) |
429 | E42902 | Please wait until the current report list query finishes before making a new query |
Get a list of test locations
GET /api/2.0/locations
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.
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", "region": "Asia Pacific", "default": false, "account_has_access": true, "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.region | The location's region group name | string |
attributes.default | Whether this is the default location | boolean |
attributes.account_has_access | Whether your account has access to this 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 browsers
GET /api/2.0/browsers
Get a list of test browsers currently available to you.
Note: If you are looking to test your page with a diverse set of screen resolutions, launch a simulated device test (PRO only). Refer to simulated devices list for more information.
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.
Note: If you are looking to test your page with a diverse set of screen resolutions, launch a simulated device test (PRO only). Refer to simulated devices list for more information.
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 | object |
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 a list of simulated devices
GET /api/2.0/simulated-devices
Get a full list of simulated devices and their details. See reference values for a full list.
Use the simulate_device
option in Start a test to simulate the display of your site with a specific device.
Successful Response
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \ https://gtmetrix.com/api/2.0/browsers HTTP/1.1 200 OK { "data": [ { "attributes": { "category": "phone", "dppx": 3, "height": 896, "manufacturer": "Apple", "name": "iPhone 11 Pro/11 Pro Max/12 Pro Max", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.5 Mobile/15E148 Safari/604.1 GTmetrix", "width": 414 }, "id": "iphone_xs_max", "type": "simulated_device" }, { ... }, ... { ... } ] }
Property | Description | Type |
---|---|---|
data | A list of Simulated Device | array of objects |
Get simulated device details
GET /api/2.0/simulated-devices/{simulated_device_id}
Get details about a simulated device by ID.
URI values
Parameter | Description | Type |
---|---|---|
simulated_device_id | The simulated device ID | string |
Successful Response
curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \ https://gtmetrix.com/api/2.0/simulated-devices/{simulated_device_id} HTTP/1.1 200 OK { "data": { "id": "iphone_xs_max", "type": "simulated_device" "attributes": { "category": "phone", "dppx": 3, "height": 896, "manufacturer": "Apple", "name": "iPhone 11 Pro/11 Pro Max/12 Pro Max", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.5 Mobile/15E148 Safari/604.1 GTmetrix", "width": 414 } } }
Parameter | Description | Type |
---|---|---|
data | A simulated device | object |
Simulated Device Resource
Property | Description | Type |
---|---|---|
type | The resource type. Always has the value "simulated_device" | string |
id | The simulated device ID (See reference values for a full list) | string |
attributes.category | The category of the device ("phone" or "tablet)" | string |
attributes.name | The device's name | string |
attributes.manufacturer | The device's manufacturer | string |
attributes.user_agent | The browser user-agent used for the analysis | string |
attributes.height | The device's display height - sets the height of the viewport for the analysis | integer (pixels) |
attributes.width | The device's display width - sets the width of the viewport for the analysis | integer (pixels) |
attributes.dppx | the device's pixel ratio - sets the pixel ratio used for the analysis | number (1 - 5) |
Possible errors
HTTP status | Error code | Error message |
---|---|---|
404 | E40408 | simulated device 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, "api_refill_amount": 10, "account_type": "Basic", "account_pro_analysis_options_access": false, "account_pro_locations_access": false, "account_whitelabel_pdf_access": false } } }
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 |
data.attributes.api_refill_amount | API credit refill amount during next API refill | number |
data.attributes.account_type | GTmetrix plan account type | string |
data.attributes.account_pro_analysis_options_access | Whether your account has access to PRO analysis options such as simulate device or custom DNS | boolean |
data.attributes.account_pro_locations_access | Whether your account has access to PRO test locations. See Locations | boolean |
data.attributes.account_whitelabel_pdf_access | Whether your account has access to White-labeled PDF reports. See example | boolean |
data.attributes. | boolean |
Reference Values
The following are common examples and fixed reference values you may find useful.
Analysis Options
An object representing analysis options set during a test. These are the same attributes used for Test Parameters. See Start a test for a complete list of attributes.
Sample object
Note: This example does not contain all possible Test Parameter attributes.
{ "data": { "id": "{report_id}", "type": "analysis-options", "attributes": { "adblock": 1, "browser": "{browser_id}", "browser_dppx": "2", "browser_height": "896", "browser_width": "414", "block_url": [ "https://blocked.domain.com" ], "cookies": [ "name=value" ], "dns": [ "example.com:1.1.1.1" ], "httpauth_password": "password", "httpauth_username": "gtmetrix", "location": "{location_id}", "report": "lighthouse", "retention": 12, "throttle": "9000/5000/125" "url": "https://gtmetrix.com/", "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36", "video": 1, } }, "meta": { "versions": { "lighthouse": "11.0.0", "chrome": "117.0.0.0" } } }
Filmstrip Data
An object representing a filmstrip of screenshots captured during page load. Only available for Lighthouse Reports. See Get a report resource.
You can either use each of the screenshot's frame_id
to
generate links to fetch the JPEG data (equivalent to url
attribute). Or use the optional base64=1
query parameter
to return base64 encoded image data for each screenshot. See example
below.
Definitions
Attribute | Description | Notes |
---|---|---|
frame_count |
The number of different frames (images) used to generate the filmstrip | Does not equate to the number of screenshots |
frame_width |
Intrinsic image width for each screenshot | |
frame_height |
Intrinsic image height for each screenshot | |
screenshots |
Array of Screenshots (see sub attributes below) | |
screenshot.frame_id |
0-index frame id for screenshot. See get Report resource to fetch the JPEG image. | |
screenshot.timing |
Float number in miliseconds, representing the timestamp during pageload when this screenshot was approximately taken. | From Lighthouse |
screenshot.url |
API URL endpoint to fetch the screenshot JPEG data. | Not included if base64=1 query param is passed during request. |
screenshot.data |
Base64 encoded JPEG string for this screenshot. | Only included if base64=1 query param is passed during request. |
Sample object
Note: This example assumes base64=1
query param was not used.
{ "data": { "id": "{report_id}", "type": "filmstrip", "attributes": { "frame_count": 5, "frame_width": 230, "frame_height": 498, "screenshots": [ { "timing": 361.590125, "frame_id": "0", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=0" }, { "timing": 723.18025, "frame_id": "0", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=0" }, { "timing": 1084.770375, "frame_id": "0", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=0" }, { "timing": 1446.3605, "frame_id": "1", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=1" }, { "timing": 1807.950625, "frame_id": "2", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=2" }, { "timing": 2169.54075, "frame_id": "3", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=3" }, { "timing": 2531.130875, "frame_id": "3", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=3" }, { "timing": 2892.721, "frame_id": "4", "url": "https://gtmetrix.com/api/2.0/reports/{report_id}/resources/filmstrip-frame.jpg?id=4" } ] } } }
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.
See Get a list of simulated devices for a programmatic way to obtain the list.
Device type | Device ID | Device full name | Screen resolution |
---|---|---|---|
phones | |||
iphone_xr | Apple iPhone XR | 414x896 @ 2 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/3rd Gen) | 375x667 @ 2 DPR | |
iphone_xs_max | Apple iPhone 11 Pro/11 Pro Max/12 Pro Max | 414x896 @ 3 DPR | |
iphone_x | Apple iPhone 12/12 mini/12 Pro/13 mini | 375x812 @ 3 DPR | |
iphone_13 | Apple iPhone 13/13 Pro/13 Pro Max | 390x844 @ 3 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/5a | 412x893 @ 2.625 DPR | |
pixel_6 | Google Pixel 6 | 360x800 @ 3 DPR | |
pixel_6_pro | Google Pixel 6 Pro | 360x780 @ 3 DPR | |
lumia_520 | Nokia Lumia 520 | 320x533 @ 1.5 DPR | |
oneplus_nord | OnePlus Nord/Nord 2/9/10T/10R | 412x915 @ 2.625 DPR | |
oneplus_pro | OnePlus 9 Pro/10 Pro | 412x920 @ 3 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 S21/S21+/S21 Ultra | 360x800 @ 3 DPR | |
galaxy_s22 | Samsung Galaxy S22/S22+ | 360x780 @ 3 DPR | |
tablets | |||
ipad_air | Apple iPad Air 4/5 | 1180x820 @ 2 DPR | |
ipad | Apple iPad Mini 2/3/4 | 1024x768 @ 2 DPR | |
ipad_pro | Apple iPad Pro (2022) | 1112x834 @ 2 DPR | |
ipad_2 | Apple iPad 2 | 1024x768 @ 1 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 (15/10 Mbps, 100ms) | 15000/10000/100 |
4G (9/5 Mbps, 125ms) | 9000/5000/125 |
4G Slow (5/1 Mbps, 150ms) | 5000/1000/150 |
3G (1.6 Mbps/768 Kbps, 200ms) | 1600/768/200 |
3G Slow (750/500 Kbps, 250ms) | 750/500/250 |
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
Jul 5th, 2024
- Expanded info regarding browsers and simulated devices
May 15th, 2024
- Added
anonymize_user_agent
analysis option test parameter
October 11th, 2023
- Added Report Resource
filmstrip.json
andfilmstrip-frame.jpg
endpoints to fetch filmstrip screenshots during page load - Fixed Lighthouse JSON to return original filmstrip and final screenshot base64 encoded data
- Added Analysis Options and Filmstrip Data reference values with examples
September 1st, 2023
- Added documentation on report PDF resource endpoint returning 429 error
August 11th, 2023
- Fixed being able to search using GTmetrix grade (
gtmetrix_grade
) attribute for the/pages/{page_id}/reports
endpoint - Added more searchable/sortable numeric attributes to the
/pages/{page_id}/reports
endpoint
September 28th, 2022
- Added
url
,report
andpage
attributes to test object - Added
browser
andlocation
reference links to test object /tests
list endpoint now allows fetching non API tests- Added
url
,test
,page
,source
,browser
,location
,created
andexpires
attributes to report object - Added
analysis_options
endpoint for report links object - Added
/pages
,/pages/{page_id}
and related page functionality endpoints - Added
:bool
special filter attribute to allow changing the boolean filter concatenation operator (AND/OR) for endpoints that allow filtering - Added
region
andaccount_has_access
attributes to location object - Added
/simulated-devices
and/simulated-devices/{simulated_device_id}
endpoints - Added
api_refill_amount
,account_type
as well as account feature access flags to status object
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