Retrieve Axe Watcher Results with axe-watcher-results

axe-watcher-results retrieves the results of a completed Axe Watcher scan from Axe Developer Hub and turns them into a pass/fail signal for a CI pipeline.

Prerequisites

Before you run axe-watcher-results, you need:

• An Axe Developer Hub API key (a UUID).
• The project ID for the Axe Developer Hub project the scan was sent to (a UUID).
• A completed Axe Watcher scan for the commit you want to check.

Install

axe-watcher-results is distributed as a self-contained binary for Linux, macOS, and Windows. Download the binary for your platform from the Downloads page (access requires an axe DevTools for Web entitlement), then follow Preparing Binaries after Download to make it executable and, on macOS, clear the quarantine attribute.

Put the binary on your PATH (or reference it by path) so you can run it as axe-watcher-results.

Authenticate

axe-watcher-results reads your Axe Developer Hub API key from the AXE_DEVHUB_API_KEY environment variable. Set it once before running any command — in your shell for local use, or in your CI system's secret store for a pipeline:

export AXE_DEVHUB_API_KEY=<your-api-key>

The examples below assume this variable is set.

Look Up Results for a Commit (CI Gating)

Run axe-watcher-results sessions get with your project ID and a Git commit SHA:

axe-watcher-results sessions get <project-id> <commit-sha>

• <project-id>: the project's UUID.
• <commit-sha>: a 7-40 character Git commit SHA that already has a completed Axe Watcher scan.

This is the lookup that gates a build: if the run's issue count exceeds your project's a11y threshold, axe-watcher-results exits with code 10 (see Exit Codes). For example, with --format=json:

{
  "project": "your-project-name",
  "project-id": "7347af86-ff4e-4e14-8957-8fc2255ed4ec",
  "commit-sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
  "run-url": "https://axe.deque.com/axe-watcher/projects/7347af86-ff4e-4e14-8957-8fc2255ed4ec/branches/main/compare/0d4a85a2-9e6f-44ef-b814-fee8412abeb0/0d4a85a2-9e6f-44ef-b814-fee8412abeb0?settings_hash=0757ca72c5e10951ddbb2ede4edab06e&issues_over_a11y_threshold=2",
  "issues": 17,
  "new-issues": 17,
  "resolved-issues": 0,
  "issues-over-a11y-threshold": 2,
  "page-states": 2,
  "difference-in-page-states": 0,
  "created-at": "2026-07-07T18:13:00.641Z",
  "message": "Run exceeded the a11y threshold by 2."
}

If you parse the output in a script, use --format=json: the field names above are stable. The default --format=text output is meant for humans reading build logs, not for parsing.

Look Up Results for a Session

You can also look up a specific scan by its session ID instead of a commit SHA:

axe-watcher-results sessions get <project-id> <session-id>

<session-id> is a session UUID. axe-watcher-results tells a session ID apart from a commit SHA by its shape (a UUID versus a 7-40 character hex string), so you pass it in the same position. The <project-id> argument is still required and validated, even though a session lookup resolves its project from the session and API key rather than from the argument.

Use --detail=summary (the default) for issue counts by severity and rule, or --detail=full to get the complete result document as raw JSON (this ignores --format).

--format=json --detail=summary looks like this:

{
  "report_id": "14c16b50-a6ce-46ab-9974-0ad3b94eafde",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "4.0.0"
  },
  "test_details": {
    "test_id": "0d4a85a2-9e6f-44ef-b814-fee8412abeb0",
    "start_date": "2026-07-07T18:13:00.641Z",
    "end_date": "2026-07-07T18:13:05.472Z"
  },
  "commit": {
    "sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
    "author": "Jane Doe",
    "author_email": "jane@example.com",
    "message": "fix: correct login form labels",
    "branch_name": "main",
    "tag": "",
    "repository_url": "https://github.com/your-org/your-repo"
  },
  "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.11/color-contrast?application=axeAPI",
        "count": 2
      }
    ]
  }
}

If the scan is still processing, axe-watcher-results polls the server (up to 5 minutes) and writes progress to stderr; if the scan doesn't finish processing in time, it exits with code 11.

List Sessions for a Project

The sessions list subcommand lists a project's recorded scan sessions, which is useful for finding a session ID to look up:

axe-watcher-results sessions list <project-id>

Filter the results with --git-branch, --commit-sha, --git-url, --created-after/--created-before (ISO-8601 timestamps), --created-by-user-email, and --is-canonical-source. Use --page-size (1-100) and --after to page through results. sessions list also accepts --format, --network-timeout-seconds, and --verbose/-v, which behave the same as for sessions get.

Options

These options apply to the sessions get command (commit-SHA and session-ID lookups):

--version (on the root axe-watcher-results command) prints the axe-watcher-results version and exits; --help is available on every command.

Output goes to stdout as clean text or JSON; progress and error messages go to stderr, so you can capture stdout for build logs without extra parsing.

CI Gating Example

Run axe-watcher-results as a step after your Axe Watcher scan completes, using a commit SHA so the exit code reflects the a11y threshold:

# AXE_DEVHUB_API_KEY is provided by your CI system's secret store
axe-watcher-results sessions get --format=json "$PROJECT_ID" "$GIT_COMMIT_SHA"

A non-zero exit fails the calling step. See Exit Codes for what each code means and how to respond to it.

Exit Codes

Recovering from Exit 12

Exit 12 means the commit has scan results, but Axe Developer Hub has nothing to compare them against. Axe Developer Hub selects a baseline in this order:

1. A prior session on the same commit SHA.
2. The most recent session on a different SHA on the same branch.
3. The current session itself, but only if the session is canonical (see Use Axe Watcher in Continuous Integration (CI) Environments).

If none of these are available and the session isn't canonical, Axe Developer Hub returns a 404 and axe-watcher-results exits with code 12. To recover:

• Re-run the Axe Watcher scan with CI=true set, so the session becomes canonical and self-compares on a cold start.
• Run an additional scan, against this commit or a prior commit on the same branch, to seed a baseline.