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

{
  "success": true,
  "data": {
    "projects": [
      {
        "id": 99999,
        "name": "sampleproject.com",
        "createdBy": {
          "id": 000,
          "name": "sampleUser"
        },
        "recurring": false,
        "active": true,
        "advanced": true,
        "nextScanDate": null,
        "pageCount": 1,
        "lastScanDetails": {
          "reportId": 4846,
          "thBuildUuid": "0smnl-af0njbkd7rjieiadfrg-b",
          "lastScanDate": "2025-01-07T07:49:08.309Z",
          "scanStatus": "completed",
          "accessibility": {
            "status": "completed",
            "pageCount": 1,
            "issueCount": 75,
            "componentCount": 21,
            "webUrl": "https://accessibility.browserstack.com/site-scanner/projects/browserstack.com/builds?thBuildId=0smnl-af0njbkd7rjieiadfrg-b"
          },
          "scanStability": {
            "total": 1,
            "failure": 0,
            "success": 1,
            "redirect": 0
          },
          "error": null
        },
        "productsEnabled": "a11y",
        "isProcessing": false,
        "onDemandCount": 4,
        "blocked": false,
        "blockMessage": "",
        "localTesting": false,
        "accessibilitySettings": {
          "needsReview": true,
          "bestPractices": true,
          "advanced": true,
          "wcagVersion": {
            "value": "wcag21aa"
          }
        },
        "authData": {
          "isAuthConfigured": false,
          "isAuthDeleted": false,
          "authConfigId": null
        },
        "team": "*"
      }
    ],
    "filters": {
      "user": [
        {
          "label": "Mirudhula (you)",
          "value": 499
        }
      ],
      "team": [
        {
          "label": "QA",
          "value": "*"
        }
      ]
    },
    "info": {
      "page": 1,
      "pageSize": 10,
      "count": 10,
      "prev": null,
      "next": 2
    },
    "numRecurringScans": 4,
    "maxAllowedUrls": 10000,
    "allowedReccScans": null,
    "numBlockedScans": 0
  }
}

success Boolean

Indicates whether the request was successful.
data Object

Contains the list of scan projects, filter options, pagination info, and scan statistics.

▶ SHOW VALUES
- projects Array
  
  List of scan project objects.
- filters Object
  
  Available filter options for user and team.
  
  ▶ SHOW VALUES
  - user Array
    
    List of user filter options.
  - team Array
    
    List of team filter options.
- info Object
  
  Pagination metadata.
  
  ▶ SHOW VALUES
  - page Integer
    
    The current page number.
  - pageSize Integer
    
    The number of items per page.
  - count Integer
    
    The total number of results returned on the current page.
  - prev Integer
    
    The previous page number. Returns null if there is no previous page.
  - next Integer
    
    The next page number. Returns null if there is no next page.
- numRecurringScans Integer
  
  The total number of recurring scans in the account.
- maxAllowedUrls Integer
  
  The maximum number of URLs allowed per scan for the account.
- allowedReccScans Integer
  
  The maximum number of recurring scans allowed. Returns null if unlimited.
- numBlockedScans Integer
  
  The number of scan projects that are currently blocked.

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

{
  "success": true,
  "data": {
    "name": "sampleproject.com",
    "id": 99999,
    "recurring": false,
    "active": true,
    "isRunning": false,
    "createdBy": {
      "id": 000,
      "name": "sampleUser"
    },
    "scanData": {
      "pageCount": 1,
      "urlSet": [
        "https://www.example.com"
      ],
      "authData": {
        "isAuthConfigured": false,
        "isAuthDeleted": false
      },
      "localData": {
        "isEnabled": false,
        "cltEnabled": false
      },
      "sitemapBaseUrl": "",
      "crawledAt": "",
      "a11yConfig": {
        "needsReview": true,
        "bestPractices": true,
        "advanced": true,
        "wcagVersion": {
          "value": "wcag21aa"
        }
      }
    },
    "stagingBaseUrl": null
  }
}

success Boolean

Indicates whether the request was successful.
data Object

The scan configuration object.

▶ SHOW VALUES
- name String
  
  The name of the scan project.
- id Integer
  
  The unique ID of the scan project.
- recurring Boolean
  
  Whether the scan is scheduled to run on a recurring basis.
- active Boolean
  
  Whether the scan project is active.
- isRunning Boolean
  
  Whether a scan run is currently in progress.
- 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.
- scanData Object
  
  The detailed scan configuration including URLs, auth, and accessibility settings.
  
  ▶ SHOW VALUES
  - pageCount Integer
    
    The number of URLs configured for scanning.
  - urlSet Array
    
    The list of URLs to be scanned.
  - authData Object
    
    Authentication status for the scan configuration.
    
    ▶ SHOW VALUES
    - isAuthConfigured Boolean
      
      Whether an authentication configuration is set for this scan.
    - isAuthDeleted Boolean
      
      Whether the linked authentication configuration has been deleted.
  - localData Object
    
    Local testing configuration details.
    
    ▶ SHOW VALUES
    - isEnabled Boolean
      
      Whether BrowserStack Local testing is enabled.
    - cltEnabled Boolean
      
      Whether Command Line Tool (CLT) mode is enabled for local testing.
  - sitemapBaseUrl String
    
    The base URL of the sitemap used to discover pages. Empty string if not configured.
  - crawledAt String
    
    The timestamp when the sitemap was last crawled. Empty string if not applicable.
  - a11yConfig Object
    
    Accessibility scan configuration settings.
    
    ▶ SHOW VALUES
    - needsReview Boolean
      
      Whether issues that need review are included in accessibility checks.
    - bestPractices Boolean
      
      Whether best practice violations are included in accessibility checks.
    - advanced Boolean
      
      Whether advanced accessibility rules are enabled.
    - wcagVersion Object
      
      The WCAG guideline version used for accessibility checks.
      
      ▶ SHOW VALUES
      - value String
        
        The WCAG version used for the scan (for example, wcag21aa or wcag22aaa).
- stagingBaseUrl String
  
  The staging URL for the scan project. Returns null if not configured.

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

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.
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.
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

success Boolean

data Object

projects Array

filters Object

user Array

team Array

info Object

page Integer

pageSize Integer

count Integer

prev Integer

next Integer

numRecurringScans Integer

maxAllowedUrls Integer

allowedReccScans Integer

numBlockedScans Integer

Get scan details

Request parameters

proj_id* Integer

current_user_id String

Response attributes 200 application/json

success Boolean

data Object

name String

id Integer

recurring Boolean

active Boolean

isRunning Boolean

createdBy Object

id Integer

name String

scanData Object

pageCount Integer

urlSet Array

authData Object

isAuthConfigured Boolean

isAuthDeleted Boolean

localData Object

isEnabled Boolean

cltEnabled Boolean

sitemapBaseUrl String

crawledAt String

a11yConfig Object

needsReview Boolean

bestPractices Boolean

advanced Boolean

wcagVersion Object

value String

stagingBaseUrl String

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

wcagVersion Object

value String

authConfigId Integer

localTestingInfo Object

localIdentifier String

enabled Boolean

Response attributes 200 application/json

success Boolean

data Object

projectId Integer

Response attributes `200` `application/json`

proj_id^* Integer

Response attributes `200` `application/json`

name^* String

scanData^* Object

Response attributes `200` `application/json`