GTmetrix REST API v2.0

Your API Details

An API key is needed to use the GTmetrix REST API or the GTmetrix for WordPress plugin.

You must be logged in to view your API details.

Log in  or  Sign Up

Table of Contents

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

Each GTmetrix plan level has a certain allowance for Daily API Credits.

When you first generate an API key, you are given 5 trial API credits (including Basic/Free users), which are useful for testing purposes.

When your API credits fall below your account's Daily API Credit allowance, they are then refilled according to your plan’s allowance.

The credit refill time is shown in the Account Details module on your Account page.

Note that credits do not accumulate past your account's Daily API Credit allowance.

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.1 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
detail 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.

For location/browser, GTmetrix will use your default Analysis Options set in your Account page if none are supplied.

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 24
browser Browser ID string No 3
report

Report type:

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

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

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

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

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

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

will override simulate_device preset user-agent. 		string No
browser_width Set the width of the viewport for the analysis. Also requires browser_height to be set.

will override simulate_device preset width. 		integer (pixels) No 1366
browser_height Set the height of the viewport for the analysis. Also requires browser_width to be set.

will override simulate_device preset height. 		integer (pixels) No 768
browser_dppx Set the device pixel ratio for the analysis. Decimals are allowed.

will override simulate_device preset dppx. 		number (1 - 5) No 1
browser_rotate Swaps the width and height of the viewport for the analysis. integer (0, 1) No 0

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 overridden.

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. It must be supplied alongside at least one other filter.

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",
        "page_tags":         ["{tag_id}"],
        "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.page_tags Array of the tag IDs attached to the page of this report (see page tags) array of strings
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.gtmetrix_score GTmetrix score (0-100) conversion from grade integer 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
resource-summary resource_summary Download the report resource summary in JSON format

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",
        "page_tags": ["{tag_id}"]
      },
      "links": {
        "retest": "https://gtmetrix.com/api/2.0/pages/{page_id}/retest",
        "performance_monitor": "https://gtmetrix.com/api/2.0/pages/{page_id}/performance_monitor",
        "performance_alert_conditions": "https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_conditions",
        "performance_alert_events": "https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_events",
        "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.attributes.page_tags Array of the tag IDs attached to this page (see page tags) array of strings
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 analogous 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, page_tag and any numeric based report attributes from above.

Note that url filtering is done through a fuzzy search.

By default the page_tag filter matches pages that have all of the listed tags attached; with filter[:bool]=OR it matches pages that have at least one of them. Comma separated tags and repeated filter parameters are both supported, up to 500 tags. An unknown tag ID matches no pages.

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. It must be supplied alongside at least one other filter.

Allowed values: AND (default), OR 		?filter[url]=gtmetrix
?filter[created:gt]=1617680457
?filter[page_tag]={tag_id}
?filter[page_tag]={tag_id}&filter[page_tag]={tag_id}
?filter[page_tag]={tag_id},{tag_id}
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",
          "page_tags": ["{tag_id}"]
        },
        "links": {
          "retest": "https://gtmetrix.com/api/2.0/pages/{page_id}/retest",
          "performance_monitor": "https://gtmetrix.com/api/2.0/pages/{page_id}/performance_monitor",
          "performance_alert_conditions": "https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_conditions",
          "performance_alert_events": "https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_events",
          "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 E40402 Page not found

Update page monitoring

POST /api/2.0/pages/{page_id}/performance_monitor
Content-Type: application/vnd.api+json

Enable or disable monitoring for a single page, or change its monitoring frequency.

URI values

Parameter Description Type
page_id The page ID identifying the page string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/pages/{page_id}/performance_monitor \
      -d '
{
  "data": {
    "type": "performance_monitor",
    "attributes": {
      "frequency": "daily"
    }
  }
}'

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).

Monitor Parameters

Supply your desired monitoring frequency as a property in the attributes object.

Property Description Type Required
frequency Desired monitoring frequency.

Valid values: no, none, hourly, daily, weekly, monthly

no and none disables monitoring for this page; any other value enables it at that frequency.

hourly monitoring may not be available on your plan. 		string Yes

Successful Response

Returns the updated page, in the same format as Get a page.

Possible errors

HTTP status Error code Error message
400 E4001 Invalid or missing frequency value
403 E40303 Monitoring update not permitted, for example:
  Monitoring is not allowed with the selected browser,
  Your plan does not allow hourly monitoring,
  Your plan does not allow monitoring in the selected location/browser, or
  Monitoring limit exceeded (no available monitoring slots left on your plan)
404 E40402 Page not found
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

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",
        "page_tags":         ["{tag_id}"],
        "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 E40402 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, created, expires, 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. It must be supplied alongside at least one other filter.

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",
        "page_tags":         ["{tag_id}"],
        "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

Attach tags to a page

POST /api/2.0/pages/{page_id}/attach_tags
Content-Type: application/vnd.api+json

Attach one or more tags to a page. Supply the tag IDs in the page_tags array. Tags that are already attached are not affected.

URI values

Parameter Description Type
page_id The page ID identifying the page string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/pages/{page_id}/attach_tags \
      -d '
{
  "page_tags": ["{tag_id}", "{tag_id}"]
}'
Property Description Type Required
page_tags Array of tag IDs to attach to the page (at least one, at most 500) array of strings Yes

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).

Successful Response

The updated page is returned, including its new page_tags attribute.

HTTP/1.1 200 OK

{
  "data": {
    "type": "page",
    "id": "{page_id}",
    "attributes": {
      "url": "https://gtmetrix.com/",
      "page_tags": ["{tag_id}"],
      ...
    },
    ...
  }
}

Possible errors

HTTP status Error code Error message
403 E40301 Your organization role does not permit this operation
404 E40402 Page not found
404 E40417 Tag not found (an unknown tag ID was supplied in the page_tags array)
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Detach tags from a page

POST /api/2.0/pages/{page_id}/detach_tags
Content-Type: application/vnd.api+json

Detach one or more tags from a page. Supply the tag IDs in the page_tags array.

URI values

Parameter Description Type
page_id The page ID identifying the page string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/pages/{page_id}/detach_tags \
      -d '
{
  "page_tags": ["{tag_id}"]
}'

The request properties are the same as attaching tags to a page.

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).

Successful Response

The updated page is returned, including its new page_tags attribute.

HTTP/1.1 200 OK

{
  "data": {
    "type": "page",
    "id": "{page_id}",
    "attributes": {
      "url": "https://gtmetrix.com/",
      "page_tags": [],
      ...
    },
    ...
  }
}

Possible errors

HTTP status Error code Error message
403 E40301 Your organization role does not permit this operation
404 E40402 Page not found
404 E40417 Tag not found (an unknown tag ID was supplied in the page_tags array)
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Get a list of page tags

GET /api/2.0/page_tags

Get the list of all tags belonging to your account.

Successful Response

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

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "tag",
      "id": "{tag_id}",
      "attributes": {
        "name": "Production",
        "description": "Customer facing pages",
        "color": "FFFFFF"
      },
      "links": {
        "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
      }
    },
    {
      "type": "tag",
      "id": "{tag_id}",
      "attributes": {
        "name": "Staging",
        "color": "FF0000"
      },
      "links": {
        "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
      }
    }
  ]
}

Tag Resource

Property Description Type
type The resource type (always tag) string
id The tag ID identifying the tag (used in the /page_tags/{tag_id} endpoints) string
attributes.name The tag name (unique per account) string
attributes.description The tag description, displayed as a tooltip on hover (only present when set) string
attributes.color The tag background color, as a 6 character hex value (without a leading '#') string
links.self URL to fetch this tag string

Create a page tag

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

Create a new tag for your account. Supply the tag properties in the attributes object.

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/page_tags \
      -d '
{
  "data": {
    "type": "tag",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FF8800"
    }
  }
}'
Property Description Type Required
name The tag name. Must be unique within your account, 45 characters max string Yes
description The tag description, displayed as a tooltip on hover. 255 characters max string No
color The tag background color, as a 6 character hex value (without a leading '#'). Defaults to FFFFFF (white) string No
id When data.id is supplied, the existing tag with that ID is updated instead of a new tag being created (the response is 200 OK).

An unknown tag ID will result in a 404 error 		string No

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).

Successful Response

HTTP/1.1 201 Created

{
  "data": {
    "type": "tag",
    "id": "{tag_id}",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FF8800"
    },
    "links": {
      "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
    }
  }
}

Possible errors

HTTP status Error code Error message
400 E4001 Invalid POST body parameter
400 E40009 Invalid tag parameter (invalid tag name or description, or tag name must be unique)
403 E40301 Your organization role does not permit this operation
403 E40303 Tag limit reached for your plan
404 E40417 Tag not found (an unknown tag ID was supplied in data.id)
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Get a page tag

GET /api/2.0/page_tags/{tag_id}

Get a single tag in its full form.

URI values

Parameter Description Type
tag_id The tag ID identifying the tag string

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/page_tags/{tag_id}

HTTP/1.1 200 OK

{
  "data": {
    "type": "tag",
    "id": "{tag_id}",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FFFFFF"
    },
    "links": {
      "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
    }
  }
}

Possible errors

HTTP status Error code Error message
404 E40417 Tag not found

Update a page tag

POST /api/2.0/page_tags/{tag_id}
Content-Type: application/vnd.api+json

Update an existing tag with a partial attribute update. Supply only the tag properties you wish to change in the attributes object; any omitted attribute keeps its current value.

URI values

Parameter Description Type
tag_id The tag ID identifying the tag string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/page_tags/{tag_id} \
      -d '
{
  "data": {
    "type": "tag",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FFFFFF"
    }
  }
}'

Unlike the create endpoint, this update endpoint supports partial attributes: you may omit name, description, or color and those fields will retain their current values. The tag is identified by the tag_id in the URL (supplying data.id is not accepted).

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).

Successful Response

The updated tag is returned.

HTTP/1.1 200 OK

{
  "data": {
    "type": "tag",
    "id": "{tag_id}",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FFFFFF"
    },
    "links": {
      "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
    }
  }
}

Possible errors

HTTP status Error code Error message
400 E4001 Invalid POST body parameter
400 E40009 Invalid tag parameter (invalid tag name or description, or tag name must be unique)
403 E40301 Your organization role does not permit this operation
404 E40417 Tag not found
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Delete a page tag

This operation is irreversible — the tag reference will be removed from any pages that had it. Proceed with caution.

DELETE /api/2.0/page_tags/{tag_id}

Delete a tag.

URI values

Parameter Description Type
tag_id The tag ID identifying the tag string

Successful Response

Tag has been successfully deleted.

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

  HTTP/1.1 200 OK

  {
    "data": {
      "type": "tag",
      "id":   "{tag_id}"
    }
  }

Possible errors

HTTP status Error code Error message
403 E40301 Your organization role does not permit this operation
404 E40417 Tag not found

Attach pages to a tag

POST /api/2.0/page_tags/{tag_id}/attach
Content-Type: application/vnd.api+json

Attach one or more pages to a tag. Supply the page IDs in the page_ids array. Pages that are already attached to the tag are not affected.

URI values

Parameter Description Type
tag_id The tag ID identifying the tag string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/page_tags/{tag_id}/attach \
      -d '
{
  "page_ids": ["{page_id}", "{page_id}"]
}'
Property Description Type Required
page_ids Array of page IDs to attach to the tag (at least one, at most 500) array of strings Yes

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).

Successful Response

HTTP/1.1 200 OK

{
  "data": {
    "type": "tag",
    "id": "{tag_id}",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FFFFFF"
    },
    "links": {
      "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
    }
  }
}

Possible errors

HTTP status Error code Error message
403 E40301 Your organization role does not permit this operation
404 E40402 Page not found (an unknown page ID was supplied in the page_ids array)
404 E40417 Tag not found
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Detach pages from a tag

POST /api/2.0/page_tags/{tag_id}/detach
Content-Type: application/vnd.api+json

Detach one or more pages from a tag. Supply the page IDs in the page_ids array.

URI values

Parameter Description Type
tag_id The tag ID identifying the tag string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/page_tags/{tag_id}/detach \
      -d '
{
  "page_ids": ["{page_id}"]
}'

The request properties are the same as attaching pages to a tag.

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).

Successful Response

HTTP/1.1 200 OK

{
  "data": {
    "type": "tag",
    "id": "{tag_id}",
    "attributes": {
      "name": "Production",
      "description": "Customer facing pages",
      "color": "FFFFFF"
    },
    "links": {
      "self": "https://gtmetrix.com/api/2.0/page_tags/{tag_id}"
    }
  }
}

Possible errors

HTTP status Error code Error message
403 E40301 Your organization role does not permit this operation
404 E40402 Page not found (an unknown page ID was supplied in the page_ids array)
404 E40417 Tag not found
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Get performance alert events for a page

GET /api/2.0/pages/{page_id}/performance_alert_events

Get a paginated list of performance alert events triggered by a page, most recent first.

URI values

Parameter Description Type
page_id The page ID identifying the page string

URI query parameters

Parameter Description Example
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]=2

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_events

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "performance_alert_event",
      "id": "{alert_event_id}",
      "attributes": {
        "timestamp": 1663780062,
        "report_id": "{report_id}",
        "alerts": [
          {
            "metric":    "onload",
            "operator":  ">",
            "threshold": 3000,
            "value":     5124
          }
        ],
        "recipient_emails": ["[email protected]"]
      }
    },
    {
      "type": "performance_alert_event",
      "id": "{alert_event_id}",
      "attributes": {
        "timestamp": 1663780062,
        "alerts": [
          {
            "error":      "Error generating Lighthouse report",
            "error_slug": "eBoOTx6c"
          }
        ],
        "recipient_emails": ["[email protected]"]
      }
    },
    { ... },
    ...
    { ... }
  ],
  "links": {
    "prev": "/api/2.0/pages/{page_id}/performance_alert_events?page[number]=1",
    "next": "/api/2.0/pages/{page_id}/performance_alert_events?page[number]=3",
  },
  "meta": {
    "curr_page": 2
  }
}
Property Description Type
data.type The resource type. Always has the value "performance_alert_event" string
data.id The alert event ID string
data.attributes.timestamp Time when this alert event was triggered integer (unix timestamp)
data.attributes.report_id ID of the report generated by the test that triggered this alert, if any string
data.attributes.alerts Alert conditions that were triggered, and/or report-generation failures that occurred.

A triggered condition entry has metric (see Performance Alert Metrics), operator, threshold (the configured alert condition) and value (the value that triggered it).

A report-generation failure entry has error (a human-readable message) and error_slug (an identifier for the failure) instead. 		array of objects
data.attributes.recipient_emails E-mail addresses notified for this alert event array of strings
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
404 E40402 Page not found

Get performance alert conditions for a page

GET /api/2.0/pages/{page_id}/performance_alert_conditions

Retrieve a page's current performance alert condition configuration.

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}/performance_alert_conditions

HTTP/1.1 200 OK

{
  "data": {
    "type": "performance_alert_conditions",
    "id": "{page_id}",
    "attributes": {
      "create_video": false,
      "conditions": [
        {
          "metric": "onload",
          "operator": ">",
          "value": 3000
        }
      ],
      "send_to": [
        { "email": "[email protected]", "channel": "email" }
      ]
    }
  }
}
Property Description Type
data.type The resource type. Always has the value "performance_alert_conditions" string
data.id The page ID identifying the page string
data.attributes.create_video Whether a video recording of the page load is kept when an alert triggers (PRO only) boolean
data.attributes.conditions The page's currently-configured alert conditions.

Each entry has metric (one of the IDs listed under Performance Alert Metrics), operator (<, =, >) and value (the threshold, in the same units the Report API reports that metric in). 		array of objects
data.attributes.send_to Recipients notified when an alert triggers.

Only present for Team organizations; each entry has email and channel (currently always email). 		array of objects

Possible errors

HTTP status Error code Error message
404 E40402 Page not found

Update performance alert conditions for a page

POST /api/2.0/pages/{page_id}/performance_alert_conditions
Content-Type: application/vnd.api+json

Replace a page's performance alert conditions, video option, and (for Team organizations) recipients. This always replaces the full set of conditions and, when send_to is supplied, the full set of recipients.

URI values

Parameter Description Type
page_id The page ID identifying the page string

Request Object

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
      -X POST -H Content-Type:application/vnd.api+json \
      https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_conditions \
      -d '
{
  "data": {
    "type": "performance_alert_conditions",
    "attributes": {
      "create_video": false,
      "conditions": [
        {
          "metric": "onload",
          "operator": ">",
          "value": 3000
        }
      ],
      "send_to": [
        { "email": "[email protected]" }
      ]
    }
  }
}'

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).

Attributes

Supply the desired configuration as properties in the attributes object.

Property Description Type Required
create_video Keep a video recording of the page load if an alert is triggered (PRO only) boolean No (default false)
conditions The full list of alert conditions for this page (max 10). Always replaces the current list; an empty array removes all alert conditions.

Each entry is an object with:
  metric — the metric ID to alert on, which must match one of the IDs listed under Performance Alert Metrics
  operator — one of <, =, >
  value — the threshold (non-negative number), in the same units the Report API reports that metric in (e.g. milliseconds for time-based metrics, bytes for size-based metrics) 		array of objects Yes
send_to Recipients to notify when an alert triggers, as a list of objects with an email (must match a Team organization member's account e-mail) and optional channel (currently only email, the default).

Available for Team organizations only, where it is required. 		array of objects Team organizations only (required for them)

Successful Response

Returns the updated configuration, in the same format as Get a page's performance alert conditions.

Possible errors

HTTP status Error code Error message
400 E40009 send_to is required for Team organizations
400 E40010 Unknown send_to recipient (no Team organization member found with that e-mail address)
400 E40011 send_to is only available for Team organizations
403 E40301 Your organization role does not permit this operation
404 E40402 Page not found
415 E41500 Unsupported media type (Request must use Content-Type: application/vnd.api+json)

Delete performance alert conditions for a page

DELETE /api/2.0/pages/{page_id}/performance_alert_conditions

Remove all of a page's performance alert conditions.

URI values

Parameter Description Type
page_id The page ID identifying the page string

Successful Response

  curl -u e8ddc55d93eb0e8281b255ea236dcc4f: -X DELETE \
      https://gtmetrix.com/api/2.0/pages/{page_id}/performance_alert_conditions

  HTTP/1.1 200 OK

  {
    "data": {
      "type": "performance_alert_conditions",
      "id":   "{page_id}"
    }
  }

Possible errors

HTTP status Error code Error message
403 E40301 Your organization role does not permit this operation
404 E40402 Page not found

Get a list of test locations

GET /api/2.0/locations

Visit the Pricing Page for more information on Basic and Additional 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",
        "region":   "Asia Pacific",
        "default":  false,
        "account_has_access": true,
        "browsers": [ "{browser_id}", ... ],
        "ips":      [ "{ip_address}", ... ],
        "servers":  3,
        "active_location": true
      }
    },
    { ... },
    ...
    { ... }
  ]
}
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}", ... ],
      "ips":      [ "{ip_address}", ... ],
      "servers":  3,
      "active_location": true
    }
  }
}
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
data.attributes.name The location name string
data.attributes.region The location's region group name string
data.attributes.default Whether this is the default location boolean
data.attributes.account_has_access Whether your account has access to this location boolean
data.attributes.browsers List of Browser IDs supported by this location array of strings
data.attributes.ips List of IP addresses assigned to this location array of strings
data.attributes.servers Number of servers that are up in this location integer
data.attributes.active_location Whether this location has at least one server up boolean

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. 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",
        "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. 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
data.attributes.name The browser display name string
data.attributes.browser The browser short name string
data.attributes.platform The browser platform (desktop/android) string
data.attributes.device The browser device type (phone/tablet); if applicable string
data.attributes.adblock Whether this browser supports AdBlock boolean
data.attributes.lighthouse Whether this browser supports Lighthouse (non-legacy) testing boolean
data.attributes.cookies Whether this browser supports specifying cookies boolean
data.attributes.filtering Whether this browser supports URL filtering boolean
data.attributes.http_auth Whether this browser supports HTTP authentication boolean
data.attributes.throttle Whether this browser supports connection throttling boolean
data.attributes.video Whether this browser supports video generation boolean
data.attributes.dns Whether this browser supports custom DNS boolean
data.attributes.user_agent Whether this browser supports setting a custom User Agent boolean
data.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
data.attributes.category The category of the device ("phone" or "tablet)" string
data.attributes.name The device's name string
data.attributes.manufacturer The device's manufacturer string
data.attributes.user_agent The browser user-agent used for the analysis string
data.attributes.height The device's display height - sets the height of the viewport for the analysis integer (pixels)
data.attributes.width The device's display width - sets the width of the viewport for the analysis integer (pixels)
data.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 milliseconds, representing the timestamp during page load 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_x Apple iPhone 12 mini/13 mini 375x812 @ 3 DPR
iphone_xs_max Apple iPhone 13 Pro Max/14 414x896 @ 3 DPR
iphone_13 Apple iPhone 13/13 Pro/14/16e 390x844 @ 3 DPR
iphone_16_plus Apple iPhone 15+/iPhone 16+ 430x932 @ 3 DPR
iphone_16 Apple iPhone 15/16 393x852 @ 3 DPR
iphone_16_pro Apple iPhone 16 Pro 402x874 @ 3 DPR
iphone_16_max Apple iPhone 16 Pro Max 440x956 @ 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
pixel_9 Google Pixel 8/9/9 Pro 412x915 @ 2.625 DPR
lumia_520 Nokia Lumia 520 320x533 @ 1.5 DPR
oneplus_nord_ce OnePlus Nord CE4 Lite 392x873 @ 2.75 DPR
oneplus_nord OnePlus Nord/Nord 2/9/10T/10R 412x915 @ 2.625 DPR
oneplus_pro OnePlus OnePlus 9 Pro/10 Pro 412x920 @ 3 DPR
oneplus_13 OnePlus 12/13 411x905 @ 3.5 DPR
galaxy_a56 Samsung Galaxy A36/A56 412x893 @ 2.625 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 S23/S24/S25 360x780 @ 3 DPR
galaxy_s25_ultra Samsung S24 Ultra/S25 Ultra 384x824 @ 3.75 DPR
galaxy_s25_edge Samsung S25+/S25 Edge 384x832 @ 2.8125 DPR
tablets
ipad_air Apple iPad Air 4/5 1180x820 @ 2 DPR
ipad_air_6 Apple iPad Air 6/Pro 1366x1024 @ 2 DPR
ipad Apple iPad Mini 6/7 1024x768 @ 2 DPR
ipad_pro Apple iPad Pro (2024) 1112x834 @ 2 DPR
ipad_2 Apple iPad 6/7 1024x768 @ 1 DPR
ipad_10 Apple iPad 9/10 1080x810 @ 2 DPR
nexus_7 Google Nexus 7 960x600 @ 2 DPR
nexus_10 Google Pixel Tablet 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_s10_ultra Samsung Galaxy Tab S9 Ultra/S10 Ultra 1480x924 @ 2 DPR
galaxy_tab_s10_plus Samsung Galaxy Tab S9+/S10+ 1400x876 @ 2 DPR
galaxy_tab_s7 Samsung Galaxy Tab S9/S10 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

Resource Summary

An object representing the breakdown of page resources by type, including counts and sizes in bytes (transferred and uncompressed) for each resource category.

Name Description
document

HTML documents, including the main page

font

Web fonts loaded by the page

image

Image files loaded on the page

media

Video resources loaded on the page

script

JavaScript files loaded on the page

stylesheet

CSS stylesheets used to style the page

other

Resources that do not fall into any other category

Sample object

{
  "document": {
    "label": "HTML",
    "count": 2,
    "size_transferred": 139443,
    "size_uncompressed": 896765
  },
  "font": {
    "label": "Fonts",
    "count": 2,
    "size_transferred": 379252,
    "size_uncompressed": 379252
  },
  "image": {
    "label": "Images",
    "count": 5,
    "size_transferred": 323228,
    "size_uncompressed": 337122
  },
  "media": {
    "label": "Videos",
    "count": 0,
    "size_transferred": 0,
    "size_uncompressed": 0
  },
  "other": {
    "label": "Other",
    "count": 14,
    "size_transferred": 7621,
    "size_uncompressed": 16127
  },
  "script": {
    "label": "JavaScript",
    "count": 6,
    "size_transferred": 161484,
    "size_uncompressed": 441990
  },
  "stylesheet": {
    "label": "CSS Stylesheets",
    "count": 3,
    "size_transferred": 57786,
    "size_uncompressed": 384445
  }
}

Performance Alert Metrics

The metrics that can be used in a page's performance alert conditions (see Update performance alert conditions for a page). Supply the Metric ID exactly as listed below.

An alert condition's threshold is given in the same units the metric is described in below — milliseconds for time-based metrics, bytes for size-based metrics — which are also the units the Report API expresses these metrics in. Note that these metric IDs are specific to alert conditions and do not always match the corresponding report attribute name.

The metrics are grouped below as they appear in the Dashboard's alert settings. Legacy metrics are only reported by Legacy reports.

Metric ID Name Description
Performance Scores
gtmetrix_score GTmetrix Score Overall GTmetrix score (0–100), converted from the GTmetrix grade (A = 90, B = 80, C = 70, D = 60, E = 50, F = 0)
performance_score Performance Score GTmetrix Performance score (0–100), reflecting how quickly the page loads for the user
structure_score Structure Score GTmetrix Structure score (0–100), reflecting how well the page is built for optimal performance
Performance Metrics
first_contentful_paint First Contentful Paint Time (ms) until the first text or image is painted
largest_contentful_paint Largest Contentful Paint Time (ms) until the largest content element in the viewport is painted
total_blocking_time Total Blocking Time Total time (ms) the main thread was blocked between First Contentful Paint and Time to Interactive
cumulative_layout_shift Cumulative Layout Shift Unitless score measuring how much visible content shifts around during page load
time_to_interactive Time to Interactive Time (ms) until the page becomes reliably interactive
speed_index Speed Index How quickly (ms) the contents of the page are visibly populated
Page Timings
redirect_time Redirect Duration Time (ms) spent following redirects before the HTML page request
connect_time Connection Duration Connection time (ms) for the HTML page request (sum of blocked, DNS, connect and send times; may be 0 if the request was redirected)
backend_time Backend Duration Time (ms) spent waiting for the server to respond to the HTML page request
ttfb Time to First Byte Time (ms) until the first byte of the HTML page is received (redirect + connection + backend duration)
onload Onload Time Time (ms) until the browser's window.onload event fires
fully_loaded Fully Loaded Time Time (ms) until network activity settles after onload
Page Details
total_size Total Page Size Total size (bytes) of the page and all of its resources
requests Total Page Requests Total number of requests made to fetch the entire page
Legacy & Other Metrics
html_size HTML Size Size (bytes) of the HTML document itself (may be the compressed size)
first_paint First Paint Time (ms) until the browser first renders anything
dom_interactive DOM Interactive Time Time (ms) until the browser finished parsing the document
dom_content_loaded DOM Content Loaded Time Time (ms) until the DOMContentLoaded event fires
dom_content_loaded_time DOM Content Loaded Duration Time (ms) the DOMContentLoaded event JavaScript takes to complete
onload_time Onload Duration Time (ms) the window.onload event JavaScript takes to complete
rum_speed_index RUM Speed Index Variation of Speed Index calculated from the browser's paint timings
pagespeed_score PageSpeed Score PageSpeed score (0–100). Legacy reports only
yslow_score YSlow Score YSlow score (0–100). Legacy reports only

Changelog

September 15th, 2026

  • Added /pages/{page_id}/performance_alert_events endpoint to retrieve performance alert events triggered by a page
  • Added /pages/{page_id}/performance_monitor endpoint to enable/disable monitoring, or update the frequency, for a single page
  • Added GET, POST and DELETE /pages/{page_id}/performance_alert_conditions endpoints to retrieve, replace, or remove a page's performance alert conditions
  • Added Performance Alert Metrics reference values
  • Added page tag management endpoints: /page_tags and /page_tags/{tag_id}
  • Added page_tags attribute to page and report resources
  • Added tag attach/detach endpoints: /page_tags/{tag_id}/attach, /page_tags/{tag_id}/detach, /pages/{page_id}/attach_tags and /pages/{page_id}/detach_tags
  • Added page_tags filter support to /pages endpoint for filtering pages by tag slugs with AND/OR boolean logic

June 9th, 2026

  • Added servers integer attribute (number of servers that are up) to /locations and /locations/{location_id} endpoints
  • Added active_location boolean attribute (whether the location has at least one server up) to /locations and /locations/{location_id} endpoints

April 8th, 2026

  • Added /reports/{report_id}/resources/resource-summary endpoint
  • Added resource-summary link in report data responses

April 24th, 2025

  • Added ips string array attribute to /locations/{location_id} endpoint

Nov 6th, 2024

  • Added complementary gtmetrix_score data attribute to /reports/{report_id} endpoint

July 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