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:

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

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

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

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

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

This parameter incurs additional credit costs.
integer (0, 1) No 0
stop_onload Stop the test at window.onload instead of after the page has fully loaded (ie. 2 seconds of network inactivity). integer (0, 1) No 0
throttle Throttle the connection. Speed measured in Kbps, latency in ms. See Connection Throttling reference section for sample values. string (down/up/latency) No
allow_url Only load resources that match one of the URLs on this list. This uses the same syntax as the web front end. Array of strings (URL) No
block_url Prevent loading of resources that match one of the URLs on this list. This occurs after the Only Allow URLs are applied. This uses the same syntax as the web front end. Array of strings (URL) No
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/status
Get the current account details

Successful Response

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

HTTP/1.1 200 OK

{
  "data": {
    "type": "user",
    "id":   "e8ddc55d93eb0e8281b255ea236dcc4f",
    "attributes": {
      "api_credits": 1497,
      "api_refill":  1618437519,
      "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:

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

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

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

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

Letter Grade to Score breakdown:

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

Changelog

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 and filmstrip-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 and page attributes to test object
  • Added browser and location reference links to test object
  • /tests list endpoint now allows fetching non API tests
  • Added url, test, page, source, browser, location, created and expires 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 and account_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 numbers not integers
  • Add more details to filter and sort documentation for "Get a list of tests"
  • Add more details to Lighthouse Report JSON extended data
  • OpenAPI spec: renamed report_slug parameter to report_id for consistency

July 13th, 2021

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

May 3rd, 2021

  • GTmetrix API v2.0 launched

Cookie Policy

By clicking "Allow All" you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View cookie details

Deny Allow All
×