Get Results Programatically

The downloadable reports REST service allows you to download a summary of your Axe Developer Hub accessibility results as JSON data, for further processing or importing into other software. The GET service has two required parameters:

• API key - Find a personal API key corresponding to your project or add a new API key in the Axe Account Portal. Choose an Axe Developer Hub API key if your project uses the web APIs, CLI, or Watcher. Use an Axe DevTools Mobile API key for mobile projects.
• Project ID - Provide the project ID for the corresponding project data you want to download. Find your project ID in Axe Developer Hub.

You can use two optional parameters to limit your query to a specific Git branch or a specific Git commit SHA.

Request Summary

• Endpoint: https://axe.deque.com/api-pub/watcher/downloadable/report
• Request: GET
• Headers (Required):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Query parameters:
  • project_id (Required)
    • Description: Specifies the project ID for the project's report you want to download. This parameter is required.
    • Example usage: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Optional)
    • Description: Returns the downloadable report for the specified Git branch name.
    • Example usage: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Optional)
    • Description: Returns the downloadable report for the specified Git commit SHA.
    • Example usage: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Example curl Request

curl -L -H 'Accept: application/json' -H 'X-API-Key: <DEQUE_API_KEY>' 'https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>'

Example Response Body

{
  "report_id": "a4990926-3014-4799-aa39-7aca31fce412",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "3.20.2"
  },
  "test_details": {
    "test_id": "da0c79a5-6f1e-4692-a255-5757629208fa",
    "start_date": "2025-05-05T20:02:31.883Z",
    "end_date": "2025-05-05T20:02:42.789Z"
  },
  "commit": {
    "sha": "f73ea5a02386b359ffa79a76473f7a5ad41759d5",
    "author": "John Doe",
    "author_email": "john.doe@example.com",
    "message": "Merge pull request #233 from deque/221-add-examples-for-using-global-config-fields-2",
    "branch_name": "main",
    "repository_url": "https://github.com/dequelabs/watcher-examples.git",
    "tag": null
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "heading-order",
        "rule_help": "Heading levels should only increase by one",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/heading-order?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "landmark-one-main",
        "rule_help": "Document should have one main landmark",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/landmark-one-main?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "page-has-heading-one",
        "rule_help": "Page should contain a level-one heading",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/page-has-heading-one?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "region",
        "rule_help": "All page content should be contained by landmarks",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/region?application=axeAPI",
        "count": 9
      }
    ]
  }
}

Response Object

The following sections describe the JSON objects in the response body.

Top-Level Structure

source Object

Contains information about the product that generated the report:

test_details Object

Contains information about the test execution:

commit Object

Contains information about the Git commit associated with the test:

devhub_summary Object

Contains summary information about accessibility issues found:

issue_count_by_impact Object

Breaks down issues by impact level:

issue_count_by_rule Array

Each object in this array represents a rule with the following structure:

Additional Responses

202 Processing

This response indicates that the report is still being generated, and you need to retry your request after waiting.

Response body

{
  "message": "Report is still processing",
  "state": "PROCESSING"
}

400 Bad Request

The value supplied for commit_sha isn't a SHA-1 value.

Response body

{
  "error": "commit_sha must be a valid SHA-1 hash"
}

401 Unauthorized

One of the following error messages will accompany the 401 Unauthorized response.

The API key specified isn't valid

Response body

{
  "error": "Invalid API key"
}

There is no required header with an API key:

Response body

{
  "error": "X-API-Key or Authorization header required"
}

404 Not Found

One of the following error messages will accompany the 404 Not Found response.

The SHA value used with commit_sha could not be located

This error indicates that there is no data for this SHA in the axe Developer Hub data, which usually means that the test suite was not run against this Git commit. Note that this is the same error as returned with a branch name that doesn't exist. (See the next error.)

Response body

{
  "error": "Session not found"
}

The value provided for branch_name doesn't exist

This error response is the same as the previous error (if the SHA supplied with the commit_sha query parameter doesn't exist in the axe Developer Hub data).

Response body

{
  "error": "Session not found"
}

The value supplied for project_id doesn't exist

This error response is the same as the previous 404 errors.

Response body

{
  "error": "Session not found"
}

Handling a 202 Processing Response

This demonstration shell script shows how to use curl to re-request your report if you receive a 202 Processing response. Since test suites may find numerous accessibility violations, our system may require additional time to process all of the results before the report is ready to download. We recommend using the example below to create a script that will continually retry and see if the results are available yet. It will retry the request up to 20 times, with a five-second delay between attempts.

The sample requires the API_KEY environment variable to be set to your API key and PROJECT_ID to be set to your project ID.

#!/bin/bash

URL="https://axe.deque.com/api-pub/watcher/downloadable/report"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."
    
    # Get both status and response
    STATUS=$(curl -s -w '%{http_code}' -L -H "Accept: application/json" -H "X-API-Key: $API_KEY" -o "$TEMP_FILE" "$URL?project_id=$PROJECT_ID")
    
    case $STATUS in
        200)
            echo "Success!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 0
            ;;
        202)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 1
            ;;
    esac
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1