Reports

A Report represents a site validation report you've created in Rocket Validator. It contains a list of web pages that were found from the starting url, and the HTML and accessibility issues that were found.

Attributes

ID

Unique report ID.

Starting URL

Initial URL, that the Spider will use as the initial request. The Spider will include the internal links from that starting URL, and then (if Deep Crawl is enabled) recursively include the linked web pages from those, until the Max Pages limit is reached.

Initial URLs

A list of URLs to be included on the first run of the Spider. Newline-separated.

Exclusions

A list of URLs or partial paths to tell the Spider to skip matching URLs. Newline-separated.

Domain

Domain from the starting URL.

Max Pages

Maximum number of web pages to include. Places a limit on the Spider.

Num Pages

Actual number of web pages included in the report found by the Spider.

Rate Limit

Maximum allowed requests per second.

Deep Crawl

Boolean to indicate whether deep crawling was enabled or not. If it's enabled, the Spider witll recursively include more linked pages from the pages it finds, until the Max Pages limit is reached.

Prefer Canonical URLs

Boolean to indicate whether our crawler should use canonical URLs from your web pages, if present.

Dynamic Crawler

Boolean to indicate whether Dynamic Crawler should be used instead of the default static crawler. The Dynamic Crawler renders each web page found using a headless browser, so it's able to find links in JavaScript-powered web pages.

Perform HTML Checks

Boolean to indicate whether or not HTML checks will be performed on the web pages found.

Perform A11Y Checks

Boolean to indicate whether or not accessibility checks will be performed on the web pages found.

Device Rotated

Boolean to indicate if the emulated device viewport is rotated. The device viewport used in the report is shown via the Device relationship.

Checks

Details for the checks enabled for this report.

HTML

Details for the HTML checks, if enabled (null otherwise).

Status

HTML checks status, showing the number of checks pending, checked and failed.

Issues

Counters for the number of HTML errors and warnings. This sums the number of HTML issues on all the web pages for a particular report.

A11Y

Details for the Accessibility checks, if enabled (null otherwise).

Status

Accessibility checks status, showing the number of checks pending, checked and failed.

Issues

Counters for the number of Accessibility errors and warnings. Also includes the number of issues per each severity level (minor, moderate, serious and critical). This sums the number of Accessibility issues on all the web pages for a particular report.

Shared

Boolean, false by default. Indicates if the report can be shared with other users.

Tags

Comma-separated list of tags to categorize this report.

Inserted At

Timestamp when the report was created.

Updated At

Timestamp when the report was last updated.

Last Checked At

Timestamp when the report was last checked.

Relationships

Web Pages

The list of web pages found by the Spider for that report.

Common HTML issues

The HTML issues found on the web pages for that report, if any, grouped together by their kind.

Common A11Y issues

The accessibility issues found on the web pages for that report, if any, grouped together by their kind.

Schedule

The Scheduled Report that initiated this Report, if any.

Device

The emulated device viewport used in the accessibility checks.

Guest Token

If this report was created by one of your guest accounts, its guest account will be linked here.

Mutings

Mutings applied to this report, if any.

Example

Example: Report example

{
  "data": {
    "attributes": {
      "checks": {
        "a11y": {
          "issues": {
            "errors": 51,
            "severity": {
              "critical": 0,
              "minor": 0,
              "moderate": 1,
              "serious": 50,
              "total": {
                "errors": 51,
                "total": 51,
                "warnings": 0
              }
            },
            "warnings": 0
          },
          "status": {
            "checked": 7,
            "failed": 0,
            "pending": 0
          }
        },
        "html": {
          "issues": {
            "errors": 17,
            "warnings": 105
          },
          "status": {
            "checked": 7,
            "failed": 0,
            "pending": 0
          }
        }
      },
      "deep_crawl": true,
      "prefer_canonical_urls": true,
      "device_rotated": false,
      "domain": "dummy.rocketvalidator.com",
      "dynamic_crawler": false,
      "exclusions": [],
      "initial_urls": [],
      "inserted_at": "2024-05-14T13:54:29",
      "last_checked_at": "2024-05-14T13:54:49",
      "max_pages": 100,
      "num_pages": 7,
      "perform_a11y_checks": true,
      "perform_html_checks": true,
      "rate_limit": 5,
      "starting_url": "https://dummy.rocketvalidator.com",
      "tags": [
        "dummy"
      ],
      "shared": false,
      "updated_at": "2024-05-14T13:54:49"
    },
    "id": "2455a63a-7e16-4cbf-8455-6c9a88195142",
    "relationships": {
      "common_a11y_issues": {
        "links": {
          "related": "https://rocketvalidator.com/api/v1/reports/2455a63a-7e16-4cbf-8455-6c9a88195142/common_a11y_issues"
        }
      },
      "common_html_issues": {
        "links": {
          "related": "https://rocketvalidator.com/api/v1/reports/2455a63a-7e16-4cbf-8455-6c9a88195142/common_html_issues"
        }
      },
      "device": {
        "links": {
          "related": "https://rocketvalidator.com/api/v1/devices/c4f0f4be-e6dd-498a-b049-205be3604505"
        }
      },
      "excluded_urls": {
        "links": {
          "related": "https://rocketvalidator.com/api/v1/reports/2455a63a-7e16-4cbf-8455-6c9a88195142/excluded_urls"
        }
      },
      "mutings": {
        "links": {
          "related": "https://rocketvalidator.com/api/v1/reports/2455a63a-7e16-4cbf-8455-6c9a88195142/mutings"
        }
      },
      "web_pages": {
        "links": {
          "related": "https://rocketvalidator.com/api/v1/reports/2455a63a-7e16-4cbf-8455-6c9a88195142/web_pages"
        }
      }
    },
    "type": "report"
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Create a Report

To create a Report, send a POST request to /api/v1/reports, with a JSON payload in the body including its attributes. The only required attribute is the starting URL.

• starting_url. The initial URL where the Spider will start on.

Optional attributes

The following attributes are optional:

• deep_crawl. Boolean to enable deep crawling. Defaults to true.
• dynamic_crawler. Boolean to use the Dynamic Crawler (for JS apps) instead of the default static crawler. Defaults to false.
• prefer_canonical_urls. Boolean to indicate canonical URLs are preferrer. Defaults to true.
• max_pages. The Spider will recursively follow internal links found until this limit is reached. Defaults to 10.
• rate_limit. Limit on the number of requests per second. Defaults to 1.
• perform_html_checks. Boolean to enable checks using the W3C Validator software on the Web Pages found. Defaults to true.
• perform_a11y_checks. Boolean to enable checks using Deque Axe Core software on the Web Pages found. Defaults to false.
• store_raw_html_checks. Boolean to enable storage of the raw HTML checks. Defaults to false.
• store_raw_a11y_checks. Boolean to enable storage of the raw accessibility checks. Defaults to false.
• store_incomplete_checks. Boolean to store the Axe Core manual review checks, alongside the violations. Requires perform_a11y_checks. Defaults to false.
• initial_urls. Newline-separated list of URLs.
• exclusions. Newline-separated list of paths.
• device_id. Id of the device to be used for viewport emulation. Check the device list to see the available devices.
• device_rotated. Boolean to indicate the emulated device should be rotated. Defaults to false.
• tags. Comma-separated list of tags.
• shared. Boolean to indicate if the report can be shared with other users. Defaults to false.

Examples

The next example shows how to create a report for a given starting URL. This will use the defaults of 10 web pages, checked only for HTML issues:

Example: POST /api/v1/reports

{
  "data": {
    "attributes": {
      "starting_url": "https://dummy.rocketvalidator.com"
    }
  }
}

In the following example we're using the advanced options to create a 1,000 web pages report, with HTML and Accessibility checks, on a rotated iPhone 12/13 Pro device, tagged as dev, dummmy.

Example: POST /api/v1/reports

{
  "data": {
    "attributes": {
      "starting_url": "https://dummy.rocketvalidator.com",
      "max_pages": 1000,
      "rate_limit": 3,
      "perform_html_checks": true,
      "perform_a11y_checks": true,
      "deep_crawl": true,
      "device_id": "c4f0f4be-e6dd-498a-b049-205be3604505",
      "device_rotated": true,
      "tags": "dev,dummy"
    }
  }
}

Rocket Validator will return the created Report with a status of a 201 Created, and will start scanning the Web Pages found. You can then refresh the Report by its ID (see Retrieve a Report) to check the progress of the Report, including the checks status, pending count and issues found.

If the Report can't be created, a 422 Unprocessable Entity status will be returned, containing details about the the errors found.

Example: POST /api/v1/reports

{
  "errors": [
    {
      "detail": "Starting url has invalid format",
      "source": {
        "pointer": "/data/attributes/starting_url"
      },
      "title": "has invalid format"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

Change the Visibility of a Report

By default, reports are private and only accessible to the user who created them, and their host in case of guest users.

To change the visibility of a report, send a PATCH request to /api/v1/reports/$REPORT_ID with a payload to set the shared field to true or false. Any other payload will be rejected.

Example: PATCH /api/v1/reports/$REPORT_ID

{
  "data": {
    "attributes": {
      "shared": true
    }
  }
}

Retrieve a Report

GET /api/v1/reports/$REPORT_ID

List your Reports

GET /api/v1/reports

Filtering by URL

To include only the Reports for a given starting_url, use the filter[url] option.

For example:

GET /api/v1/reports?filter[url]=dummy.rocketvalidator.com

Filtering by tag

To include only the Reports for a given tags combination, use the filter[tags] options:

• filter[tags][mode] setting the tag combination mode, which can be any, all or none.
• filter[tags][list] including a comma-separated list of tags.

For example, this will return all reports tagged with any of dev or dummy

GET /api/v1/reports?filter[tags][mode]=any&filter[tags][list]=dev,dummy

Filtering by schedule

To show the reports created by a Schedule, use the filter[schedule_id] option.

For example:

GET /api/v1/reports?filter[schedule_id]=$SCHEDULE_ID

Filtering by Guest Accounts

If you have Guest Accounts, you can filter the report list so that it also contains the reports created by your guests.

By default, the Reports API shows only the reports created by the main account:

GET /api/v1/reports

This is equivalent to passing created_by=me like this:

GET /api/v1/reports?created_by=me

To get the list of all reports (created by main account or by guests), pass created_by=all like this:

GET /api/v1/reports?created_by=all

To get only the list of reports created by guests, pass created_by=guests like this:

GET /api/v1/reports?created_by=guests

To get only the list of reports created by an individual guest or guests, pass the tokens as comma-separated like this:

GET /api/v1/reports?created_by=guests&guest_token=1234

or

GET /api/v1/reports?created_by=guests&guest_token=1234,5678

Each report will include the guest_token used as an attribute.

You can find the token for each guest account in the Guests section, both in the guest card, and also in the CSV export.

Sorting reports

By default the list of reports is returned in descending order of the last_checked_at timestamp, that is, the most recent reports are shown first.

If you want to change the sorting order, you can do that using the sort parameter to specify the attribute to sort by, combined with the direction (asc for ascending, desc for descending).

The sortable attributes are:

url

Starting URL

num_web_pages

Number of web pages

html_issues

Number of HTML issues (errors + warnings)

html_errors

Number of HTML errors

html_warnings

Number of HTML warnings

a11y_issues

Number of accessibility issues (errors + warnings)

a11y_errors

Number of accessibility errors

a11y_warnings

Number of accessibility warnings

last_checked_at

Timestamp for the last time a report was checked

Combining one of these attributes with the asc or desc direction modifier, we get the parameter to use. For example, to sort by URL in descending order we would use url-desc.

Here is a table showing all possible combinations for your convenience:

Delete a Report

To delete an individual Report from your account, send a DELETE request to /api/v1/reports/$REPORT_ID.

DELETE /api/v1/reports/$REPORT_ID