Overview
Customers can use ObservePoint’s API to:
Create and execute website Audits and Journeys
Ingest Audit results data into internal systems
Automate nearly any task users can perform in the ObservePoint user interface
All data that ObservePoint presents in its user interface is also available via API
ObservePoint’s API is a REST API. It uses predictable, resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods. Any programming language and even some low-code tools can be used to integrate with the ObservePoint API.
Getting Started
Become familiar with the following concepts to use the ObservePoint API.
Authentication
Every ObservePoint API endpoint requires clients to authenticate by passing an API key with the request. You can find your API key on your profile page. Pass your API key via the “Authorization” header, as follows:
Authorization: api_key paste_your_api_key_here
An example of using the curl command to retrieve a list of Audits in your account:
curl -H 'Authorization: api_key paste_your_api_key_here' \
https://api.observepoint.com/v2/web-audits
Versioning
ObservePoint currently has two supported versions of its API: v2 and v3.
References for each API endpoint for both v2 and v3 are available:
Both versions of the API are fully supported and have no current plans for deprecation.
Pagination
Note: ObservePoint’s API uses the term “page” with two different meanings, depending on context:
In the context of pagination, a "page" is a subset of results from an API request.
In the context of an Audit or Journey, a "page" is a web page.
Some API endpoints use pagination to limit the size of responses, such as:
/v3/web-audits/auditId/runs/runId/reports/page-summary/pages?size=pageLimit&page=pageNumber
Endpoints that support pagination allow you to specify two parameters to control the pagination:
Pagination Input Query Parameter Name | Description |
size | The number of records the API should return per page. Allowed range: 50 - 10,000 Tip: A good rule of thumb is to set this to 100. |
page | The page number, starting at 0, that you want to request. |
To download all results, you need to make multiple requests, increasing the “page” query string argument of each request, starting at 0, until you have downloaded all results.
Each response contains a “metadata” object with a “pagination” sub-object which tells you which page number you are currently processing and the total number of records to expect.
"metadata": {
"pagination": {
"totalCount": 544,
"totalPageCount": 6,
"pageSize": 100,
"currentPageSize": 100,
"currentPageNumber": 0
}
},
// results will appear here as a JSON array
}
You will know you have downloaded all records when the total number of records you have downloaded equals “totalCount”
Pagination Output Field Name | Description |
totalCount | The total number of records (not pages) across all pages. |
totalPageCount | The total number of pages in the result. |
pageSize | The number of records in each page (note: when querying the pages from an Audit run, the records are web pages). |
currentPageSize | The size of the current page. This will be equal to “pageSize” on every request except the last one. |
currentPageNumber | Starting at 0, this is the number of the current page represented by the current request. |
API Requests
When you make a PUT or POST request to the ObservePoint API, you will need to specify a content-type header as follows:
Content-Type: application/json
When you make a PATCH request to the ObservePoint API, you will need to specify a content-type header as follows:
Content-Type: application/json-patch+json
When you make a GET request, no content-type header is needed.
API Responses
ObservePoint API responses are JSON encoded, and thus have a Content-Type of “application/json”.
Responses use conventional HTTP status codes to indicate the success or failure of an API request, as described below:
HTTP Response Code Range | Meaning |
2xx | The request was successful |
4xx | There was a mistake in your request. Read the response payload and the HTTP status code to know what was wrong. |
5xx | There is an error with the ObservePoint servers. You can retry certain 5xx errors (like 502). If retrying doesn’t resolve the problem, contact ObservePoint support. |
Rate Limiting
The ObservePoint API follows industry standard rate limiting practices. If your code generates too many API requests in a period of time, the API will respond with a 429 error.
API rate limits are enforced per API key.
What should I do if my requests get rate limited?
Dealing with rate limiting is straight forward. If your code receives a 429 response, your code should wait and retry later. Usually a few seconds will suffice. Sometimes your code will need to retry for up to 5 minutes. Your code cannot cause harm by continuing to retry when it receives a 429 response.
It's a best practice to design your code to handle 429 responses from the beginning. Don't wait until you encounter your first 429 response to write the code.
What is the rate limit?
Some ObservePoint API endpoints allow different request rates from other API endpoints. Some are measured with 1-minute granularity, and others are measured at 5-minute granularity. ObservePoint occasionally changes these settings to ensure the API can operate reliably. As a rule of thumb, if your code stays within 1,000 requests in a 5-minute period, you will not be rate limited.
Will I be charged if I hit the rate limit?
You will not be billed if your code gets rate limited. The API is designed this way to prevent you from being charged extra if your code gets rate limited.