Get Results Programmatically

Migrating to the Sessions and Results API

The new Sessions and Results API replaces this endpoint with two separate endpoints: one to list sessions for a project and one to retrieve results for a specific session. This two-step model gives you access to all sessions across branches and commits, not just the most recent one.

Equivalent request using format=summary

The Results endpoint's format=summary mode returns the same JSON shape as this endpoint. To replicate an existing request, first find the session that matches your branch or commit, then request its results:

1. List sessions to find the session_id for the branch or commit you care about, using the git_branch or commit_sha filters:

   curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
     "https://axe.deque.com/api-pub/v1/results/projects/$PROJECT_ID/sessions?git_branch=$GIT_BRANCH"

2. Request results for that session by session_id, using format=summary for the same JSON shape as this endpoint:

   curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
     "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=summary"

   important

   The new endpoint returns 204 No Content while results are being generated, not 202 Processing as this endpoint does. If you have existing code that checks for a 202 response, update it to handle 204 instead. See Session State and the Polling Pattern for a complete polling example.

Going further with format=full

If you want the complete issue-level detail beyond what the summary provides, use format=full to retrieve results in Universal JSON (Common Export Format). This format includes every accessibility issue found during the session: individual violations, incomplete checks, passes, and inapplicable rules organized by page.

curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=full"

Legacy Endpoint Reference

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

429 Too Many Requests

During periods of heavy load, this endpoint may respond with 429 Too Many Requests instead of triggering processing immediately. The underlying work stays queued, so retrying does not create duplicate processing. The response includes a Retry-After header, in seconds — wait at least that long before retrying.

Response body

{
  "error": "Too many requests. Retry after the Retry-After interval."
}

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