Blogs

GTmetrix | Website Performance Testing and Monitoring

Posted on by admin

The GTmetrix API

provides developers with an easy way to use the GTmetrix performance testing service. With the GTmetrix API, you can integrate performance testing into your development environment or application.

In addition, you can also get reports, tests, and pages not generated by the API, such as what is done through

monitoring or on demand.

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 with OpenAPI-compatible tools to get your

GTmetrix integration up and running: Download API

Access

URL

The base URL of 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

. Test costs The cost of the report

depends on the type of report you want to generate; see the report option in Test parameters for more information. Additional testing costs Report

retention

costs

Choose your retention period per report when starting a new

test

: See retention in Test parameters for more information

. API Credit

Recharges

GTmetrix Basic users receive up to 5 API credits daily. You can increase your daily API credit allowance by upgrading to GTmetrix PRO. When you first generate an API key, you are awarded 100 credits (useful for testing purposes).

Please note that your API credits are only topped up when they fall below your account’s daily API credit allowance

– credits do not accrue beyond your account’s daily API credit allocation

.

For example, a GTmetrix Basic account has a daily allowance of 5 credits. A top-up of these credits (back to 5) will occur in the next top-up period and only when your remaining credits fall below 5.

If you think your app or service will require more API credits, feel free to upgrade to a GTmetrix PRO account or contact us

.

Authentication

The GTmetrix API uses HTTP Basic Access Authentication as the 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, as in the cURL example below, which automatically generates the correct authorization header and adds it to your request. You can also generate the Authorization header yourself by following the specification instructions.

All of the API endpoints described below require authentication

. You can generate and view your API key

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

cURL

example curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \

https://gtmetrix.com/api/2.0/status Possible authentication errors

Request answers

The GTmetrix API uses the HTTP status codes 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 following documentation.

All response bodies return a JSON-encoded string. The GTmetrix API uses the JSON:API v1.0 convention for all its responses and certain requests. See the following documentation 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”: “The method does not support the endpoint” }, { … } ] }

Error properties

Common errors

Possible errors that can occur in response to any of the documented

requests

API Rate Limiting

The

GTmetrix API has a global rate limit on all API endpoints to prevent accidental or deliberate flooding of requests to the API service. Limits have been chosen that must be high enough for any reasonable use of the API. If you’re hitting the limits, consider increasing your retry times or contact us to discuss your usage scenario.

The speed limit status is communicated via X-RateLimit-* response headers, freely following the specification guidelines: X-RateLimit-Limit: {request-quota}, {request-quota};window={time-window} X-RateLimit-Remaining: {requests-remaining}

X-RateLimit-Reset: {time-remaining}

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

REST requests

Start

a test Get a list of tests Get a test Get a report Delete a report Retest a report Get a report resource Get a page Get a list of pages

Delete

a page

Retest

a page Get

the most recent report

on a page

Get

a list of

one-page

reports

Get a list of available test locations Get location details Get a list

of available browsers

Get browser details Get

a list of

available

simulated devices Get

simulated device details

Get

your account status

Reference values

Resource

usage data A collection of resource usage values, sampled approximately every hundred milliseconds, is included as a custom field in the pages object of the HAR file. This custom field, named _resourceUsage, is an array containing arrays whose values are structured as follows:

Subarray values List of

simulated devices

Note that this parameter is only available with GTmetrix PRO plans

.

See Get a list of simulated devices for the list programmatically.

Connection throttling

These are the default values for limiting the connections available on the dashboard. You can also pass a custom connection string with down/up/latency values in Kbps.

Faro Report

JSON

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

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

Change log September

28th, 2022

Added url, report, and page attributes to the test object Added browser and location reference links to the

  • /tests list endpoint of the test object that now allows non-API testing

    • Added url, test, page,

  • source, browser, location, created, and expired

    • to the report object

  • Added analysis_options endpoint for report links object

    • Added /pages, /pages/{page_id},

  • and
  • related page functionality

    • endpoints

  • Added

    • special filter attribute

  • :bool to allow changing the Boolean filter concatenation operator (AND/OR) for endpoints that allow filtering

    • Added region and account_has_access attributes to the location object Added /simulated-devices and /

  • simulated-devices/{simulated_device_id}

    • endpoints Added

  • account feature api_refill_amount, account_type, and access marks to the status

  • object

September 22, 2021

Fix “Start a test”

  • Response credits Documentation details to be non-integer numbers

    • Add more details for

  • filter and sort the documentation from “Get a test list”
  • Add more details to Lighthouse Report JSON extended data

    • OpenAPI specification:

  • Parameter renamed report_slug to report_id for consistency

July 13th, 2021

  • Fix startup test parameters: cookies, allow_url, block_url, DNS to be string array OpenAPI specification:
  • fix parameters that should be string arrays: cookies, allow_url, block_url, DNS

    • OpenAPI specification:

  • Add the missing retention parameter OpenAPI specification:
  • fix browser_dppx type to be “number” not “integer”

May 3, 2021

  • GTmetrix API v2.0 released
admin