GTmetrix REST API v2.0

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

Start a new page test with desired test parameters.

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

Request Object

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

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

Test Parameters

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

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

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

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

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

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

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

Response body

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

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

Test Resource

Possible errors

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 rentetion options.

URI values

Successful Response

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

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

  {
    "data": {
      "type": "report",
      "id":   "{report_id}",
      "attributes": {
        "url":               "https://gtmetrix.com",
        "page":              "{page_id}",
        "test":              "{test_id}",
        "source":            "api",
        "created":           1660868227,
        "expires":           1676420227,
        "gtmetrix_grade":    "A",
        "performance_score": 94,
        "structure_score":   99,
        ...
      },
      "links": {
        "har": "/api/2.0/reports/{report_id}/resources/har",
        ...
      }
    }
  }
  

Possible errors

DELETE /api/2.0/reports/{report_id}

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

  HTTP/1.1 200 OK

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

Possible errors

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

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

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

Resources

The resources available to fetch from a report

cURL example

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

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

  ...
  

Possible errors

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

Successful Response

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

  HTTP/1.1 200 OK
  {
    "data": {
      "type": "page",
      "id": "{page_id}",
      "attributes": {
        "url": "https://gtmetrix.com/",
        "created": 1651537199,
        "browser": "{browser_id}",
        "location": "{location_id}",
        "latest_report_time": 1663780062,
        "latest_report": "{report_id}",
        "report_count": 5,
        "monitored": "no"
      },
      "links": {
        "retest": "https://gtmetrix.com/api/2.0/pages/{page_id}/retest",
        "latest_report": "https://gtmetrix.com/api/2.0/pages/{page_id}/latest-report",
        "reports": "https://gtmetrix.com/api/2.0/pages/{page_id}/reports",
        "location": "https://gtmetrix.com/api/2.0/locations/{location_id}",
        "browser": "https://gtmetrix.com/api/2.0/browsers/{browser_id}"
      }
    }
  }
  

Possible errors

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.

Successful Response

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

HTTP/1.1 200 OK

{
  "data": [
    {
      "data": {
        "type": "page",
        "id": "{page_id}",
        "attributes": {
          "url": "https://gtmetrix.com/",
          "created": 1651537199,
          "browser": "{browser_id}",
          "location": "{location_id}",
          "latest_report_time": 1663780062,
          "latest_report": "{report_id}",
          "report_count": 5,
          "monitored": "no"
        },
        "links": {
          "retest": "https://gtmetrix.com/api/2.0/pages/{page_id}/retest",
          "latest_report": "https://gtmetrix.com/api/2.0/pages/{page_id}/latest-report",
          "reports": "https://gtmetrix.com/api/2.0/pages/{page_id}/reports",
          "location": "https://gtmetrix.com/api/2.0/locations/{location_id}",
          "browser": "https://gtmetrix.com/api/2.0/browsers/{browser_id}"
        }
      }
    },
    { ... },
    ...
    { ... }
  ],
  "links": {
    "prev":  "/api/2.0/pages?page[number]=2",
    "next":  "/api/2.0/pages?page[number]=4",
  },
  "meta": {
    "curr_page": 3
  }
}

Possible errors

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

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

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

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

GET /api/2.0/pages/{page_id}/latest-report

Fetches the latest report from a specific page.

URI values

Successful Response

Same response as get a report.

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

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

  {
    "data": {
      "type": "report",
      "id":   "{report_id}",
      "attributes": {
        "url":               "https://gtmetrix.com",
        "page":              "{page_id}",
        "test":              "{test_id}",
        "source":            "api",
        "created":           1660868227,
        "expires":           1676420227,
        "gtmetrix_grade":    "A",
        "performance_score": 94,
        "structure_score":   99,
        ...
      },
      "links": {
        "har": "/api/2.0/reports/{report_id}/resources/har",
        ...
      }
    }
  }
  

Possible errors

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.

Successful Response

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

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "report",
      "id":   "{report_id}",
      "attributes": {
        "url":               "https://gtmetrix.com",
        "page":              "{page_id}",
        "created":           1660868227,
        "expires":           1676420227,
        "source":            "api",
        "gtmetrix_grade":    "A",
        "performance_score": 94,
        "structure_score":   99,
        ...
      },
      "links": {
        "har": "/api/2.0/reports/{report_id}/resources/har",
        ...
      }
    },
    { ... },
    ...
    { ... }
  ],
  "links": {
    "prev":  "/api/2.0/reports?sort=created&page[number]=2",
    "next":  "/api/2.0/reports?sort=created&page[number]=4",
  },
  "meta": {
    "curr_page": 3
  }
}

Possible errors

GET /api/2.0/locations

Visit the Locations Page for more information on Basic and Premium test locations.

Successful Response

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

HTTP/1.1 200 OK

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

GET /api/2.0/locations/{location_id}

Get details of a location by ID.

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",
      "region":   "Asia Pacific",
      "default":  false,
      "account_has_access": true,
      "browsers": [ "{browser_id}", ... ]
    }
  }
}

Location Resource

Possible errors

GET /api/2.0/browsers

Get a list of 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/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"
    },
    { ... },
    ...
    { ... }
  ]
}

GET /api/2.0/simulated-devices/{simulated_device_id}

Get details about a simulated device by ID.

URI values

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

Simulated Device 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,
      "api_refill_amount": 10,
      "account_type": "Basic",
      "account_pro_analysis_options_access": false,
      "account_pro_locations_access": false,
      "account_whitelabel_pdf_access": false
    }
  }
}