GTmetrix REST API v2.0

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

Start a new page test with desired test parameters.

Note that you can only run 2 tests concurrently on a Basic account (GTmetrix PRO users get 8 concurrency) and when you exceed this limit, you will get a 429 HTTP status code. You will need to wait until one of the existing jobs completes, or retry until you get a non 429 status.

Request Object

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    -X POST -H Content-Type:application/vnd.api+json \
    https://gtmetrix.com/api/2.0/tests \
    -d '
{
  "data": {
    "type": "test",
    "attributes": {
      "url":      "https://www.gtmetrix.com",
      "location": {location_id},
      "browser":  {browser_id},
      "adblock":  1
      ...
    }
  }
}'

Note that the request must be done with the correct Content-Type header, otherwise the API will respond with a 415 error (see a list of errors below).

Test Parameters

Supply your desired test parameters as properties in the attributes object.

Note that not all options may be available to your current plan (see the table footnote).

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": 123,
    "credits_used": 7
  },
  "links": {
    "self": "/api/2.0/tests/{test_id}"
  }
}

The Location header always points to the same URL as links.self.

Possible errors

GET /api/2.0/tests

Get a paginated list of all the tests belonging to your account.

Note that the tests are only retained for 24 hours. The GTmetrix report for the URL will be retained for 1 month .

See also: Start a test

URI query parameters

You can choose to augment the returned test list by using the following query parameters in this request's URL. Consult the Test attribute list below for more information on attributes these parameters reference.

Successful Response

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

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "test",
      "id":   "{test_id}",
      "attributes": {
        "source":   "api",
        "location": {location_id},
        "browser":  {browser_id},
        "state":    "queued",
        "created":  1617680457,
        "started":  1617680459
      }
    },
    { ... },
    ...
    { ... }
  ],
  "links": {
    "prev":  "/api/2.0/tests?sort=created&page[number]=2",
    "next":  "/api/2.0/tests?sort=created&page[number]=4",
  }
}

Possible errors

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

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_slug}

If the test is complete, the API responds with a redirect to the Report result.

Response body

{
  "data": {
    "type": "test",
    "id":   "{test_id}",
    "attributes": {
      "source":   "api",
      "location": {location_id},
      "browser":  {browser_id},
      "state":    "queued",
      "created":  1617680457,
    }
  }
  "links": {
    "self": "/api/2.0/tests/{test_id}"
  }
}

Test Resource

Possible errors

GET /api/2.0/reports/{report_slug}

Retrieve the report data. Reports are the result of a completed test and contain page load information.

GTmetrix reports will be retained for 1 month.

URI values

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/reports/{report_slug}

HTTP/1.1 200 OK
Cache-Control: max-age=31536000

{
  "data": {
    "type": "report",
    "id":   "{report_slug}",
    "attributes": {
      "gtmetrix_grade":    "A",
      "performance_score": 94,
      "structure_score":   99,
      ...
    },
    "links": {
      "har": "/api/2.0/reports/{report_slug}/resources/har",
      ...
    }
  }
}

Possible errors

DELETE /api/2.0/reports/{report_slug}

Delete a report and all of its resources.

URI values

Successful Response

Report has been successfully deleted

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

HTTP/1.1 200 OK

{
  "data": {
    "type": "report",
    "id":   "{report_slug}"
  }
}

Possible errors

POST /api/2.0/reports/{report_slug}/retest

Retest a report with the same page settings. This is semantically identical to starting a new test using the same parameters as the test that generated this report.

URI values

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: -X POST \
    https://gtmetrix.com/api/2.0/reports/{report_slug}/retest

HTTP/1.1 202 Accepted
Location: /api/2.0/tests/{test_id}

...

The response is identical to starting a new test.

Possible errors

GET /api/2.0/reports/{report_slug}/resources/{resource_name}

Get a report resource.

URI values

Resources

The resources available to fetch from a report

cURL example

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/reports/{report_slug}/resource/net.har

HTTP/1.1 200 OK
Cache-Control: max-age=31536000
Content-Type: application/json

...

Possible errors

GET /api/2.0/locations

This list is limited to the test locations currently available to you. Visit the Locations Page for more information on Basic and Premium test locations.

Successful Response

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

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "location",
      "id":   "{location_id}",
      "attributes": {
        "name":     "Sydney, Australia",
        "default":  false,
        "browsers": [1,3]
      }
    },
    { ... },
    ...
    { ... }
  ]
}

GET /api/2.0/locations/{location_id}

Get details of a location by ID

Note that you can only retrieve details about locations available to you. Visit the Locations Page for more information on Basic and Premium test locations.

URI values

Successful Response

curl -u e8ddc55d93eb0e8281b255ea236dcc4f: \
    https://gtmetrix.com/api/2.0/locations/{location_id}

HTTP/1.1 200 OK

{
  "data": {
    "type": "location",
    "id":   "{location_id}",
    "attributes": {
      "name":     "Hong Kong, China",
      "default":  false,
      "browsers": [ {browser_id}, ... ]
    }
  }
}

Location Resource

Possible errors

GET /api/2.0/browsers

This list is limited to the test browsers currently available to you.

Successful Response

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

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "browser",
      "id":   "browser_id",
      "attributes": {
        "name":       "Chrome (Desktop)",
        "default":    true,
        "platform":   "desktop",
        "adblock":    true,
        "cookies":    true,
        "dns":        true,
        "filtering":  true,
        "http_auth":  true,
        "resolution": true,
        "throttle":   true,
        "user_agent": true,
        "video":      true,
        "lighthouse": true,
        "device":     ""
      }
    },
    { ... },
    ...
    { ... }
  ]
}

GET /api/2.0/browsers/{browser_id}

Get details about a browser by browser ID. This list is limited to the test browsers currently available to you.

URI values

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":     ""
    }
  }
}

Browser Resource

Possible errors

GET /api/2.0/status

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