Reports API
Intro to the Reports API
Tenon's Reports API provides quick access to a large number of important pieces of data, allowing you to understand your accessibility progress. The Reports API is the same data that is displayed on your Dashboard.
Note : The Reports API is currently a beta feature. You should anticipate some changes to the report types and content within them. We will do our best to ensure all tests are backwards-compatible.
We will be increasing the overall number of reports in the relative near term.
Making Requests
- All requests against the Reports API must be made via GET.
- All requests must include 'key' and 'type' parameters, where 'key' represents your API key and 'type' represents the type of report you want to retrieve
- Additional parameters may be required depending on the type of report. Those additional parameters are listed in the description of each report
- There are a handful of optional parameters that can be used for every report type:
- projectID: Allows you to limit all reports to a specific project
- start: Allows you to set the earliest date for which you want to retrieve data. It should be formatted as YYYYMMDD
- end: Allows you to set the earliest date for which you want to retrieve data. It should be formatted as YYYYMMDD
Using filters like projectID and start & end dates go a long way to making many of these reports more useful.
Request Examples
Sending a GET request for the following URL would retrieve the Summary report:
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=summary
Sending a GET request for the following URL would retrieve the Summary report for the specified date range:
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=summary&start=20170901&end=20171001
Response Format
All responses from the Reports API adhere to the following format:
- status: Relevant HTTP status code for the request.
- message: String of text that corresponds to the status.
- name: String to identify the name of this type of report.
- description: String that describes what the report provides.
- data: The actual report data. Note: this may be an object or it may be an array, depending on the type of report.
- time: total time, in seconds, that it took to return the response.
Response Format Example
Reports
There are two types of reports: Those which present summary data and those which list detailed data. Those which list detailed data all begin with 'list'. For instance: "List Issue Instances by Test ID" would provide full issue details for all issues relating to a specific Test ID
The following list of reports is organized alphabetically:
- Average Density
- Density Distribution
- Document Size
- Duplicate Issues
- History by docID
- Issues by Certainty
- Issues by Content Category
- Issues by Level
- Issues by Priority
- Issues by Test ID
- Issues by WCAG SC
- Issues per Page
- List Issue Instances by Test ID
- List issues by Signature
- Log Time
- Logs By Day
- Page History
- Page performance
- Pass vs. Fail
- Requests by Certainty
- Requests by Priority
- Response Codes
- Summary
- Top Errors
- True Response Codes
- Response by ID
- List Issues by Certainty
- List Issues by Priority
- List Duplicate Issues by Test ID
- List Issues by WCAG Success Criterion
- List Requests by Response Status Code
- Requests by Level
- List Issues by WCAG Level
Average Density
Returns density information for each date you have run tests.
Issue density is a better indicator of performance than issue counts and provide a glimpse into how good or bad things really are. You goal is to have the lowest density scores that you can.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=averageDensity
Response
Density Distribution
Returns the number and percentage of pages in each of the following density ranges: 0, 1-10, 11-20, 21-30, 31-40, 41-50, 51-60, 61-70, 71-80, 81-90, 91-100, 100+
Like the above, this provides insight into your overall performance. Rather than merely relying on averages, this shows you where you are among a set of distinct ranges. As above, you'll want to focus on ensuring lower issue density.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=densityDistribution
Response
Document Size
Returns the average document size, in kilobytes, for each date you have run tests.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=documentSize
Response
Duplicate Issues
Returns a list of duplicate issues as well as a count & percentage of times they occur.
Use this report to determine patterns in your sites. Identifying duplicates will allow you to prioritize what to fix first.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=duplicateIssues
Response
History by docID
Tenon's Test API lets you set a docID as one of your API request parameters. This value is useful in providing a way to uniquely identify a page - especially during things like functional UI testing or when testing pages that have machine-generated URLs. You can set any arbitrary string as your docID to help identify what page (or component) was tested. Then, you can use this report type to gather performance data on that page.
Every test for that particular docID will be returned in this report. This report is very useful for tracking performance of specific pages.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=historyByDocID&docID=[DOCID_GOES_HERE]
Response
Issues by Certainty
Returns a distribution of issues organized by Certainty levels (0, 20, 40, 60, 80, 100)
This report is another good indicator of performance, though we expect the overall percentages provided will be quite predictable. Tenon's tests always have a high level of certainty, anyway.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesByCertainty
Response
Issues by Content Category
Returns issue counts and percentages organized by content categories
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesByContentCategory
Response
Note : We do not recommend statically storing the category names, as these names may change over time.
Issues by Level
Returns a distribution of issues organized by WCAG Level (A, AA, AAA)
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesByLevel
Response
Issues by Priority
Returns a distribution of issues organized by Priority levels (0, 20, 40, 60, 80, 100)
This report is another good indicator of performance, though we expect the overall percentages provided will be quite predictable. Tenon's tests always have a high level of Priority, anyway.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesByPriority
Response
Issues by Test ID
Returns a list of all tests that have been failed and a count & percentage of how many times it was failed.
Because this report focuses on raw issue counts across all tests, focus on the most frequently occurring issues. Not only does this allow you to focus on what to fix but may also guide internal training programs as well. Frequent issues of a specific type indicate ignorance around accessibility for that type of code.
Note : We do not recommend statically storing the issue titles, as the titles may change over time.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesByTid
Response
Issues by WCAG SC
Returns a list of all WCAG Success Criterion and, for each, indicates whether Tenon tests for it and if so how often you have failed tests related to that Success Criterion
This can provide an insight into your overall performance against the individual WCAG Success Criterion. Keep in mind, however, that automated accessibility testing tools are not judges and []some things cannot be tested for with an automated tool](http://www.example.com/2012/09/15/accessibility-testing-what-can-be-tested-and-how/).
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesByWcagSc
Response
Issues per Page
Returns an average count of issues per page for each date you have run tests.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=issuesPerPage
Response
List Issue Instances by Test ID
Returns a list of issues organized by Test ID.
Use this to find a fully detailed list of all issues for the specified Test ID.
Example
Request
This report type requires you to supply two additional parameters:
- tID which is the test you want to get results for.
- projectID the project you want results from.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssueInstances&tID=[tID]&projectID=[PROJECT_ID_HERE]
Response
List issues by Signature
Returns a list of issues based on a specified issue signature.
Example
Request
This report type requires you to supply two additional parameters:
- signature which is the signature for which you want to retrieve instances.
- projectID the project you want results from.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssuesBySignature&signature=[signature]&projectID=[PROJECT_ID_HERE]
Response
Log Time
Returns the average execution time, in seconds, for each date you have run tests.
Example
Request
Returns the average execution time, in seconds, for each date you have run tests.
Response
Logs By Day
Returns the number of test runs for each date you have run tests.
Example
Returns the number of test runs for each date you have run tests.
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=logsByDay
Response
Page History
Returns a response summary for each test run against a specified URL
You can use this report to track the performance of a specific URL. Each time you test the same URL, its result summary will be listed in this report.
Example
Request
This report type requires you to supply an additional parameter - url which is the address of the page you want to retrieve the History for.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=pageHistory&url=http://www.example.com
Response
Page performance
Returns a list of the 10 worst performing pages
As the description shows, these are the worst performing pages. You'll want to prioritize repairing these pages over others.
Important if this data includes a lot of pages with only 3 or 4 issues and a very high error density (like 2000% or more) this means your server is not returning proper HTTP status code for errors. This may also mean you're trying to test local/ dev environments that Tenon cannot access. The most obvious indication that this is happening is when you see "title": "-NO TITLE-" in the listings that have such high density. Addressing this lack of appropriate HTTP responses will be important, because it will skew average densities and not allow the true poor performing URLs to be listed here.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=pagePerformance
Response
Pass vs. Fail
Returns data on the number & percentage of tests passing vs. tests failing for each date you have run tests.
Use this report to assist in tracking performance over time.
Note : It is very common to have a high percentage of tests passed. This is because Tenon has a lot of tests, many of which might not be relevant based on your site's code.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=passVsFail
Response
Requests by Certainty
Returns a count & percentage listing requests organized by Certainty levels (0, 20, 40, 60, 80, 100).
Tenon's Test API allows you to explicitly set the minimum certainty level you want to see for the issues in your test results. This report type shows you what certainty level(s) you've been using.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=requestsByCertainty
Response
Requests by Priority
Returns a count & percentage listing requests organized by Priority levels (0, 20, 40, 60, 80, 100).
Tenon's Test API allows you to explicitly set the minimum priority level you want to see for the issues in your test results. This report type shows you what priority level(s) you've been using.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=requestsByPriority
Response
Response Codes
Returns a list of each applicable type of Tenon response code and a count & percentage of each.
You should aim for 100% '200' responses. Use this type of report to determine if you're frequently submitting invalid requests to the API.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=responseCodes
Response
Summary
Returns high-level performance stats on a number of items.
This report provides a useful overview of your performance. Use the start and end parameters to create snapshots to compare performance over time.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=summary
Response
Top Errors
Returns a list of the 10 most frequently occurring errors.
This provides a quick glimpse into your most frequent errors. Use this to help prioritize remediation efforts. You should also use this report to help guide internal training for web staff.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=topErrors
Response
True Response Codes
Returns a list of HTTP status codes for the pages that were tested and the number of times tested pages returned that status
Use this report to help diagnose possible problems with the pages you're testing. For instance, if this report shows a lot of responses that are 400 and above, you should research why.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=trueResponseCodes
Response
Response by ID
Returns the stored response for a specific Accessibility Test Run from Tenon's Test API
This is mostly a convenience report, allowing you to retrieve a stored response.
Example
Request
This report type requires you to supply an additional parameter - responseID which is the specific Test API response you want to retrieve.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=responseByID&responseID=[RESPONSE_ID_HERE]
Response
List Issues by Certainty
Returns a full list of all issues in a specific project based on their 'certainty' score.
Example
Request
This report type requires you to supply two additional parameters:
- projectID which is the specific project you want data from
- certainty which is the certainty score you want issues for
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssuesByCertainty&projectID=[PROJECT_ID_HERE]&certainty=[DESIRED_CERTAINTY]
Response
List Issues by Priority
Returns a full list of all issues in a specific project based on their 'priority' score.
Using a specified 'priority' score allows you to target accessibility issues to repair in a way that has the highest positive impact.
Example
Request
This report type requires you to supply two additional parameters:
- projectID which is the specific project you want data from.
- priority which is the priority score you want issues for.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssuesByPriority&projectID=[PROJECT_ID_HERE]&priority=[DESIRED_PRIORITY]
Response
List Duplicate Issues by Test ID
Returns a list of duplicate issues organized by Test ID.
Use this to find a fully detailed list of all duplicate issues for the specified Test ID.
Note: Depending on how much testing you've done this might return a ton of results and take a long time to generate. This report will be more directly actionable if you provide a projectID and/ or start and end dates.
Example
Request
This report type requires you to supply two additional parameters:
- tID which is the test you want to get results for. -projectID the project you want results from.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listDuplicateIssuesByTestID&tID=[TEST_ID_HERE]&projectID=[PROJECT_ID_HERE]
Response
List Issues by WCAG Success Criterion
Returns a full list of all issues that are mapped against a specific WCAG Success Criterion.
This report allows you to target compliance for specific WCAG Success Criterion.
Examaple
Request
This report type requires you to supply two additional parameters:
- sc which corresponds to the numeric number of the WCAG Success Criterion (i.e. '1.1.1', etc.).
- projectID the project you want results from.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssuesByWcagSc&sc=[WCAG_SC_HERE]&projectID=[PROJECT_ID_HERE]
Response
List Requests by Response Status Code
Returns a full list of all issues that are mapped against a specific content category.
This report allows you to target compliance for specific content category.
Example
Request
This report type requires you to supply two additional parameters:
- contentCategory which corresponds to the name or a specific content category (i.e. 'images'). Possible token values can be one of the following:
- Images
- Tables
- Cascading Stylesheets (CSS)
- Forms
- Navigation
- Frames
- Document Structure
- Text Content
- Client-side Scripting
- Embedded Content
- Keyboard Accessibility & Focus Control
- Site-Wide Concerns
- projectID the project you want results from
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssuesByContentCategory&contentCategory=[CATEGORY_NAME_HERE]&projectID=[PROJECT_ID_HERE]
Response
Requests by Level
Returns a count & percentage listing requests organized by WCAG Level (A, AA, AAA)
Tenon's Test API allows you to explicitly set the minimum WCAG Level you want to see for the issues in your test results. This report type shows you what WCAG Level(s) you've been using.
Example
Request
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=requestsByLevel
Response
List Issues by WCAG Level
Returns a full list of all issues mapped to a specific WCAG Level (A, AA, AAA).
This report allows you to focus on issues based on a specific WCAG conformance level
Example
Request
This report type requires you to supply two additional parameters:
- level the desired WCAG Level.
- projectID the project you want results from.
https://tenon.io/api/reports/index.php?key=[API_KEY_GOES_HERE]&type=listIssuesByLevel&level=[LEVEL_GOES_HERE]&projectID=[PROJECTID_GOES_HERE]