Getting Started with the PageSpeed.ONE API
This guide will walk you through the first steps with the PageSpeed.ONE monitoring API. Discover what you need to do, where to obtain your key, and how to glean insights into your websites’ speed from the API data.
This guide offers a quick entry into the topic and does not replace the full API documentation.
What the API Offers
The public API serves to automate your work with test results:
- You can download aggregated CrUX metrics.
- You can access the history of PageSpeed.ONE Score (SPS).
- You can check the status of the Watchdog.
- You can write notes into graphs.
Where is the API Available?
The public PageSpeed.ONE monitoring API is hosted at the following URL:
Production URL: https://api.pagespeed.one/.
To give it a quick try, use the command line:
curl https://api.pagespeed.one/health
This will return the API's "health status", confirming that everything is functioning.
Automate your work with speed data — metrics, Watchdog, and notes in graphs.
What Do I Need to Access the Data?
Access to the API is tied to real PageSpeed.ONE testing suites. API keys are assigned to a team. You need a team plan and configuration that supports API:
- Be part of a team where you have access to one of the paid testing suites, such as PLUS.
- Be an administrator in this team to generate API keys.
Ensure you can see the API settings after logging into your account under team settings. You can then proceed with setting up API keys.
Obtaining an API Key
Protected requests are authorized with an organization key (the so-called "Bearer token"). This key belongs to a single team, and all operations can only be performed on that team's data.
- Log in to PageSpeed.ONE monitoring in your browser.
- Select the appropriate team.
- Open team (organization) settings.
- In the settings, find the section for Public API and key management.
- Before generating, choose the permission level:
- Read-only — this API key will allow only reading speed data (suitable for assignment to, say, an external agency).
- Read and write — for operations that modify data, such as creating notes in tests (be mindful of who you assign this key to).
- Generate a new key. Copy the key to a password manager.
- Handle the key with care, as you would a password: use HTTPS for transfer, never store it in a repository; if data leaks or periodically, revoke the key and create a new one.
For each request, send the header Authorization: Bearer <YOUR_API_KEY> to use our API.
How Do I Find the Hash of a Specific Test Suite?
Test suites are units you see on the team dashboard. For PLUS tests, they correspond to a single website's measurement, its URL, and competition.
You can also manually find a test suite hash in the URL of the test suite:
https:/app/r/7f3c9a2b1d4e8/
→ testHash in this case is 7f3c9a2b1d4e8
The correct URL of a test suite is recognizable by the format /app/r/{testHash}/.
Do not use other segments from the address (e.g., the team hash in the path /app/{something}/dashboard).
A complete list of valid hashes for your team's test suites (PLUS, START including trial periods; excluding purely FREE measurements) can also be retrieved from the API by calling GET /v1/tests.
First Try
You can list all relevant team test suites (see above). Or immediately verify a specific hash:
Try checking if you have access to a given test suite:
curl 'https://api.pagespeed.one/v1/tests/access-check?testHash=TEST_HASH' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'
Replace
YOUR_API_KEY— the API key, see above,TEST_HASH— the test suite hash from its URL, see above.
You should receive something like:
{
"authorized": true,
"organizationHash": "TEAM_HASH",
"testHash": "TEST_HASH"
}
organizationHash corresponds to the team segment in /app/{organizationHash}/dashboard (it's not a numeric database id).
You can also try this live in the full API documentation. There you'll find further options for data reading or writing calls.
Error Responses
Common cases:
- 401 — key missing, incorrect
Authorizationheader, or key not recognized, - 403 — key valid, but scope insufficient (e.g., read-only key for a write operation),
- 500 — unexpected server error.
The body of the response is usually a small JSON with an error field (text suitable for logs or UI; wording may change between versions).