Scan management

Use the Website Scanner REST API to list, retrieve, and create scan configurations for your websites.

Scan configurations define the URLs, accessibility settings, and schedule for your website scans. Use these endpoints to programmatically manage your scans and integrate Website Scanner into your CI/CD pipelines.

List scans

GET /api/v1/scanner

Use this endpoint to retrieve all scan configurations associated with your account. The response includes project details, last scan results, accessibility settings, and pagination metadata. You can filter the list by user or team and paginate through results using the page and page_size parameters.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  https://api-scanner.browserstack.com/api/v1/scanner

current_user_id String

Filter scans by a comma-separated list of user IDs.
team String

Filter scans by a comma-separated list of team IDs.
page Integer

Page number to retrieve. Default value is 1.
page_size Integer

Number of scan configs to return per page. Default value is 30.

Response attributes `200` `application/json`

Response

{
  "scans": [
    {
      "id": 99999,
      "name": "sampleproject.com",
      "createdBy": 499,
      "wcagVersion": "WCAG 2.1 AA",
      "recurring": false,
      "active": true,
      "nextScanDate": null,
      "status": "completed",
      "advanced": true,
      "localTestingEnabled": false,
      "authEnabled": false,
      "cookieData": {
        "isCookieConfigured": true,
        "isCookieDeleted": false,
        "cookieConfigIds": [24]
      },
      "pageCount": 1,
      "scan_url": "https://accessibility.browserstack.com/site-scanner/projects/sampleproject.com",
      "lastScanDetails": {
        "reportId": 4846,
        "lastScanDate": "2025-01-07T07:49:08.309Z",
        "scanStatus": "completed",
        "issues": 75,
        "reportSummary": {
          "failure": 0,
          "success": 1,
          "redirect": 0
        },
        "error": null
      }
    }
  ],
  "pagination": {
    "has_next": true,
    "next_page": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

scans Array

List of scan objects with basic details.

▶ SHOW VALUES
- id Integer
  
  The unique ID of the scan project.
- name String
  
  The name of the scan project.
- createdBy Integer
  
  The ID of the user who created the scan project.
- wcagVersion String
  
  The WCAG version used for the scan (for example, WCAG 2.1 AA).
- recurring Boolean
  
  Whether the scan is scheduled to run on a recurring basis.
- active Boolean
  
  Whether the scan project is active.
- nextScanDate String
  
  The ISO 8601 timestamp of the next scheduled scan run. Returns null for non-recurring scans.
- status String
  
  The current processing status of the scan.
- advanced Boolean
  
  Whether advanced accessibility scanning is enabled.
- localTestingEnabled Boolean
  
  Whether BrowserStack Local testing is enabled for this scan project.
- authEnabled Boolean
  
  Whether authentication is enabled for this scan project.
- cookieData Object
  
  Cookie configuration status for this scan project.
  
  ▶ SHOW VALUES
  - isCookieConfigured Boolean
    
    Whether a cookie configuration is set for the scan project.
  - isCookieDeleted Boolean
    
    Whether a linked cookie configuration has been deleted. The scan keeps running with the last known cookie values.
  - cookieConfigIds Array
    
    The IDs of the linked cookie configurations. Returns an empty array if none are set.
- pageCount Integer
  
  The number of URLs configured for scanning in the project.
- scan_url String
  
  The URL to the scan configuration in the BrowserStack dashboard.
- lastScanDetails Object
  
  Summary of the most recently completed scan run.
  
  ▶ SHOW VALUES
  - reportId Integer
    
    The unique ID of the most recent scan run report.
  - lastScanDate String
    
    The ISO 8601 timestamp of the most recent scan run.
  - scanStatus String
    
    The status of the last scan run. Possible values are completed or failed.
  - issues Integer
    
    The total number of issues found in the last scan run.
  - reportSummary Object
    
    Page-level scan stability metrics for the last scan run.
    
    ▶ SHOW VALUES
    - failure Integer
      
      The number of pages that failed to scan.
    - success Integer
      
      The number of pages that scanned successfully.
    - redirect Integer
      
      The number of pages that returned a redirect response.
  - error String
    
    Error message if the last scan failed. Returns null if no error occurred.
pagination Object

Pagination details for the scan list.

▶ SHOW VALUES
- has_next Boolean
  
  Whether there are more pages of results available.
- next_page String
  
  An encoded token to retrieve the next page of results. Use this value as the page query parameter in the next request.

Get scan details

GET /api/v1/scanner/{proj_id}

Use this endpoint to retrieve the full configuration of a specific scan project by its ID, including the URL set, schedule, authentication setup, and accessibility settings.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
  https://api-scanner.browserstack.com/api/v1/scanner/{proj_id}

proj_id^* Integer

The unique ID of the scan project.
current_user_id String

The user ID of the current user making the request.

Response attributes `200` `application/json`

Response

{
  "data": {
    "scanConfigInfo": {
      "name": "sampleproject.com",
      "scanConfigId": 99999,
      "createdBy": {
        "id": 499,
        "name": "sampleUser"
      },
      "wcagVersion": "WCAG 2.1 AA",
      "needsReview": true,
      "bestPractices": true,
      "recurring": false,
      "advanced": true,
      "pageCount": 1,
      "nextScanDate": null,
      "active": true,
      "isProcessing": false,
      "authEnabled": false,
      "localTestingEnabled": false,
      "cookieData": {
        "isCookieConfigured": true,
        "isCookieDeleted": false,
        "cookieConfigIds": [24]
      }
    },
    "urlList": [
      "https://www.example.com"
    ]
  }
}

data Object

Contains the scan configuration details and URL list.

▶ SHOW VALUES
- scanConfigInfo Object
  
  The scan configuration details including name, schedule, and accessibility settings.
  
  ▶ SHOW VALUES
  - name String
    
    The name of the scan project.
  - scanConfigId Integer
    
    The unique ID of the scan configuration.
  - createdBy Object
    
    Information about the user who created the scan project.
    
    ▶ SHOW VALUES
    - id Integer
      
      The unique ID of the user.
    - name String
      
      The display name of the user.
  - wcagVersion String
    
    The WCAG version used for the scan (for example, WCAG 2.1 AA).
  - needsReview Boolean
    
    Whether issues that need review are included in the scan results.
  - bestPractices Boolean
    
    Whether best practice violations are included in the scan results.
  - recurring Boolean
    
    Whether the scan is scheduled to run on a recurring basis.
  - advanced Boolean
    
    Whether advanced accessibility checks are enabled.
  - pageCount Integer
    
    The number of URLs configured for scanning.
  - nextScanDate String
    
    The ISO 8601 timestamp of the next scheduled scan run. Returns null for non-recurring scans.
  - active Boolean
    
    Whether the scan project is active.
  - isProcessing Boolean
    
    Whether a scan run is currently in progress.
  - authEnabled Boolean
    
    Whether authentication is enabled for this scan project.
  - localTestingEnabled Boolean
    
    Whether BrowserStack Local testing is enabled for this scan project.
  - cookieData Object
    
    Cookie configuration status for this scan project.
    
    ▶ SHOW VALUES
    - isCookieConfigured Boolean
      
      Whether a cookie configuration is set for the scan project.
    - isCookieDeleted Boolean
      
      Whether a linked cookie configuration has been deleted. The scan keeps running with the last known cookie values.
    - cookieConfigIds Array
      
      The IDs of the linked cookie configurations. Returns an empty array if none are set.
- urlList Array
  
  The list of URLs configured for scanning.

Create a scan configuration

POST /api/v1/scanner/create

Use this endpoint to create a new scan configuration. You can define the URLs to scan, accessibility settings, schedule, and optional authentication. Set instantRun to true to trigger a scan run immediately after creation.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://api-scanner.browserstack.com/api/v1/scanner/create \
-H 'Content-Type: application/json' \
-d '{
    "name": "www.example.com",
    "recurring": false,
    "instantRun": true,
    "scheduleStart": "2025-01-01",
    "scheduleEnd": null,
    "scanData": {
        "a11yConfig": {
        "advanced": true,
        "bestPractices": true,
        "needsReview": true,
        "wcagVersion": {
            "label": "WCAG 2.1 AA (Recommended)",
            "value": "wcag21aa"
        }
        },
        "urlSet": [
        "https://www.example.com"
        ]
    },
    "authConfigId": 441,
    "cookieConfigIds": [24, 25]
}'

name^* String

Name of the scan configuration (for example, www.example.com).
recurring Boolean

Whether to schedule the scan to run on a recurring basis. Default is true.
instantRun Boolean

Set to true to trigger a scan immediately after creating the configuration.
scheduleStart String

Start date for the scheduled scan in YYYY-MM-DD format (for example, 2024-12-29).
scheduleEnd String

End date for the scheduled scan in YYYY-MM-DD format. Pass null for no end date.
Show 4 more
scanData^* Object

Configuration data for the scan, including URLs and accessibility settings.

▶ SHOW VALUES
- urlSet Array
  
  The list of URLs to scan (for example, ["www.example.com"]).
- a11yConfig Object
  
  Accessibility scan configuration.
  
  ▶ SHOW VALUES
  - advanced Boolean
    
    Enable advanced accessibility rules. Default is true.
  - bestPractices Boolean
    
    Include best practice violations. Default is true.
  - needsReview Boolean
    
    Include issues that need review. Default is false.
  - wcagVersion Object
    
    The WCAG guideline version for the scan.
    
    ▶ SHOW VALUES
    - value String
      
      The WCAG version used for the scan (for example, wcag21aa or wcag22aaa).
authConfigId Integer

ID of the authentication configuration to use for pages that require login.
cookieConfigIds Array

IDs of cookie configurations to apply to this scan. Maximum 20 per scan.
localTestingInfo Object

Local testing configuration for scanning pages accessible only through BrowserStack Local.

▶ SHOW VALUES
- localIdentifier String
  
  The BrowserStack Local tunnel identifier.
- enabled Boolean
  
  Whether BrowserStack Local is enabled for this scan.

Response attributes `200` `application/json`

Response

{
  "success": true,
  "data": {
    "projectId": 1031225,
    "reportId": 31212
  }
}

success Boolean

Indicates whether the request was successful.
data Object

Contains the IDs of the newly created scan project and initial scan run report.

▶ SHOW VALUES
- projectId Integer
  
  The unique ID of the newly created scan project.
- reportId Integer
  
  The unique ID of the initial scan run report (created if instantRun was set to true).

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Scan management

List scans

Request parameters

current_user_id String

team String

page Integer

page_size Integer

Response attributes 200 application/json

scans Array

id Integer

name String

createdBy Integer

wcagVersion String

recurring Boolean

active Boolean

nextScanDate String

status String

advanced Boolean

localTestingEnabled Boolean

authEnabled Boolean

cookieData Object

isCookieConfigured Boolean

isCookieDeleted Boolean

cookieConfigIds Array

pageCount Integer

scan_url String

lastScanDetails Object

reportId Integer

lastScanDate String

scanStatus String

issues Integer

reportSummary Object

failure Integer

success Integer

redirect Integer

error String

pagination Object

has_next Boolean

next_page String

Get scan details

Request parameters

proj_id* Integer

current_user_id String

Response attributes 200 application/json

data Object

scanConfigInfo Object

name String

scanConfigId Integer

createdBy Object

id Integer

name String

wcagVersion String

needsReview Boolean

bestPractices Boolean

recurring Boolean

advanced Boolean

pageCount Integer

nextScanDate String

active Boolean

isProcessing Boolean

authEnabled Boolean

localTestingEnabled Boolean

cookieData Object

isCookieConfigured Boolean

isCookieDeleted Boolean

cookieConfigIds Array

urlList Array

Create a scan configuration

Request parameters

name* String

recurring Boolean

instantRun Boolean

scheduleStart String

scheduleEnd String

scanData* Object

urlSet Array

a11yConfig Object

advanced Boolean

bestPractices Boolean

needsReview Boolean

Response attributes `200` `application/json`

proj_id^* Integer

Response attributes `200` `application/json`

name^* String

scanData^* Object

Response attributes `200` `application/json`