Get Settings from the API

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard
Not for use with personal data

Use this page to read a scan's settings, look up every setting you can send when you create or edit a scan, and find which values and edits are allowed.

Method Endpoint Purpose
GET /scans/[scanId]/settings Get the full settings of a scan.
GET /axe-versions List the axe-core versions available in your axe Monitor instance.
GET /presets List presets
GET /presets/[presetId]/editability List which settings can be edited on scans that use a preset.

Get Scan Settings

Returns the full settings of one scan. You can send this response back to POST /scans or PATCH /scans/[scanId] without changing it.

Example Request

GET
https://yourcompany.dequecloud.com/monitor-public-api/v1/scans/[scanId]/settings
X-API-KEY: <your_api_key>

Required Parameters

Name Type Description
scanId Integer The unique identifier of the scan.

Example Response

Status: 200 OK

{
  "scanId": 12345,
  "presetId": null,
  "name": "Marketing Site - Production",
  "sites": ["https://www.example.com"],

  "axeCoreVersion": "latest",
  "standardLevel": "wcag22aa",
  "standardOptions": ["best-practice"],
  "customRules": [],
  "enablePdfUa": false,
  "publicShareLink": false,
  "axeReportsUpload": false,
  
  "depth": 3,
  "pageLimit": 100,
  "windowWidth": 1920,
  "windowHeight": 1080,
  "storeScreenshotsFileContent": false,
  "includeErrorPages": false,
  "excludeMimeTypes": [],
  "pdfTarget": -1,
  "pdfModifiedBetween": null,

  "commonComponents": [],
  "templateUris": [],
  "excludeCommonComponents": false,

  "scripts": [],
  "runSessionScriptFirst": false,
  "environmentVariables": [
    { "name": "ENV_API_KEY" }
  ],
  "userAgent": null,
  "referrer": null,
  "sessionEstablishment": {
    "authType": null,
    "authUserName": null
  },

  "restrictToFolder": false,
  "skipSpecificUrls": [],
  "mustHaveAll": [],
  "mustHaveAny": [],
  "mustNotHaveAny": [],
  "ignoreAllParams": false,
  "discardAnchorTags": false,
  "meaningfulParams": [],
  "meaninglessParams": [],

  "longPageOptimized": false,
  "pageWait": 0,
  "dynamicContentActive": false,
  "priority": 2,

  "scanGroups": [
    { "id": 7, "name": "Marketing Sites" }
  ],
  "teams": [
    { "name": "Digital Accessibility Team" }
  ],
  "notifyGroup": false,
  "notifyUsers": []
}

Note: Passwords, keystores, and environment variable values are never returned. They are left out of the response entirely, not returned as null. Environment variables are listed by name only.

Note: presetId is the preset applied to the scan, or null if there is none. When a preset is applied, use GET /presets/[presetId]/editability to see which settings you can edit.

Error Responses

HTTP Status Code Description
401 The API key is missing or invalid.
403 You do not have access to this scan.
404 The scan does not exist.

Full scan settings available by API

This section lists every scan setting you can send to POST /scans and PATCH /scans/[scanId], and that GET /scans/[scanId]/settings returns. Settings are grouped the same way as the scan settings in the axe Monitor user interface, and the API accepts the same values the user interface does.

Exception: credentials for starting a session are not modifiable by API for security reasons. Credentials can only be modified from the Axe Monitor user interface.

General Settings (Required)

Name Type Description
name String The name of the scan.
sites String[] The starting URLs for the scan. Only required if there are no scripts on the scan.

Accessibility Standard (Required)

Name Type Description
axeCoreVersion String The axe-core version to scan with. Use a version value from GET /axe-versions.
standardLevel String The accessibility standard to test against, for example wcag22aa. Use a value from the tags of the chosen axe-core version.

Basic Settings (Optional)

Name Type Default Description
standardOptions String[] [] Extra rule sets to include. Currently only best-practice is supported.
customRules Array [] Add phrases or words to use with the Find Text setting.
enablePdfUa Boolean false Check PDFs against PDF/UA.
publicShareLink Boolean false Create a public share link for the scan's results.
axeReportsUpload Boolean false Send scan results to Axe Reports.

Scan Scope (Optional)

Name Type Default Description
depth Integer [] How many link levels to crawl from the starting URLs.
pageLimit Integer [] The maximum number of pages scanned in each run.
windowWidth Integer 1920 Browser window width, in pixels.
windowHeight Integer 1080 Browser window height, in pixels.
storeScreenshots Boolean false Store screenshots with the scan results.
storeFileContent Boolean false Store the full page source with the scan results.
includeErrorPages Boolean false Include pages that return an HTTP error status.
excludeMimeTypes String[] [] File types to skip during the crawl, for example application/pdf.
pdfTarget Integer -1 The PDF scanning target. -1 turns PDF scanning off. Cannot be used when application/pdf is in excludeMimeTypes.
pdfModifiedFromDate Object or null null Only scan PDFs modified after a certain date.
pdfModifiedToDate Object or null null Only scan PDFs modified before a certain date.

Common Components (Optional)

Name Type Default Description
commonComponents Array [] Shared component definitions applied across pages.
templateUris String[] [] URL used to detect and consolidate common components.
excludeCommonComponents Boolean false Leave common component results out of issue counts.

Crawling and Session (Optional)

Name Type Default Description
scripts Array [] Task and session scripts. Each script has { "name", “id”, "contents", "shared", "mimeType" }.
runSessionScriptFirst Boolean false Run the session script before page scripts.
environmentVariables Array [] Variables available to scripts. Each entry is { "name" }. Values cannot be modified and are not included in responses for security reasons.
userAgent String or null null Override the browser user agent string.
referrer String or null null The HTTP Referer header value to send.
sessionEstablishment.authType String or null null The sign-in method, for example basic or keystore.
sessionEstablishment.authUserName String or null null The username used to sign in.
sessionEstablishment.script Object [] Returned when the scan has an authentication script. Each script has { "id", “name”, "contents", "mimeType", "shared" }.
sessionEstablishment.script.id Integer 0 Returned when the scan has an authentication script. To add a shared script when using the Create or Edit Scan endpoints, go to Admin → Shared Scripts in the Axe Monitor user interface. Edit a script, and retrieve the ID from the URL in the address bar: https://yourcompany-axemonitor.dequecloud.com/monitor/admin/scripts/[ID]/edit
sessionEstablishment.script.name String [] Name of the authentication script file that’s applied to the scan.
sessionEstablishment.script.contents String [] Contents of the authentication script applied to the scan.
sessionEstablishment.script.mimeType String [] File type of the script that’s applied to the scan.
sessionEstablishment.script.shared Boolean false True indicated the script is a shared script available in the Admin section of Axe Monitor.

URL Scope (Optional)

Name Type Default Description
restrictToFolder Boolean false Only crawl URLs under the path of the starting URL.
domains String[] [] Limit the scan to these domains and their subdirectories. Links to other domains are not followed. Derived from the ‘sites’ value. By default, only domains in the ‘sites’ field are scanned.
skipSpecificUrls String[] [] URL patterns to leave out of the crawl.
mustHaveAll String[] [] Only scan URLs that contain all of these text strings.
mustHaveAny String[] [] Only scan URLs that contain at least one of these text strings.
mustNotHaveAny String[] [] Skip URLs that contain any of these text strings.
ignoreAllParams Boolean false Treat URLs that differ only in query parameters as the same page. When true, meaningfulParams and meaninglessParams must be empty.
discardAnchorTags Boolean false Treat URLs that differ only in their # fragment as the same page.
meaningfulParams String[] [] Query parameters that make a URL a separate page.
meaninglessParams String[] [] Query parameters to ignore when deciding whether two URLs are the same page.

Optimization (Optional)

Name Type Default Description
longPageOptimized Boolean false Wait before scanning each page. Set the wait time with pageWait.
pageWait Integer 0 How long to wait before scanning each page, in milliseconds. Allowed range: 0 to 120000.
waitAllPages Boolean true Applies pageWait to every page in the scan. When false, it applies only to the URLs in waitPageUrls.
waitPageUrls String[] [] The URLs that pageWait applies to when waitAllPages is false.
dynamicContentActive Boolean false Wait for dynamic content, such as animations, lazy-loaded components, and embedded media, to load before scanning each page. Set the wait time with dynamicContentWait.
dynamicContentWait Integer 0 How long to wait for dynamic content before scanning each page. Used when dynamicContentActive is true.
priority Integer 2 The scan's place in the queue. Allowed range: 1 (highest) to 3 (lowest).

Schedule Frequency (Required for scheduled scans)

Name Type Description
schedule Object Contains option for manual (one-time) or scheduled scans, and details if the scan is scheduled. Each schedule has { "frequencyType", “frequencyInterval”, "frequencyData", "startDate", "startTime", “endDate”, “maxOccurrences”, “timeoutMinutes”, “timeZone.” }. Sending null removes the schedule.
schedule.frequencyType String Required with scheduled scans. How often the scan repeats. Manual creates a scan with no schedule. Week creates a weekly scans, and Month creates a monthly scan. M_DoW lets you run a monthly scan on a certain day of the week.
schedule.frequencyInterval Integer Required with scheduled scans. How many periods to wait between runs (Week or Month) . For example, 2 means every 2 weeks or months.
schedule.frequencyData String (as JSON) Which days the scan runs. The value is JSON written as a string, and what goes inside depends on frequencyType. Week: JSON Array with the days of the week to run on. Example: "[1,3]" runs every Monday and Wednesday. Month: JSON Object with the date to run on each month. A number of the day, the string “First”, or the string “Last”. First and Last are case-sensitive. Example: "{\"dayOfMonth\":15}" runs on the 15th. M_DoW: JSON Object with a weekday and which one in the month. Example: "{\"weekOfMonth\":2,\"dayOfWeek\":2}" runs on the second Tuesday. Use weekOfMonth: 5 for the last week of the month, so "{\"weekOfMonth\":5,\"dayOfWeek\":5}" is the last Friday of every month. Days are numbered 1 = Monday through 7 = Sunday.

Schedule Details (Required for scheduled scans)

Name Type Description
schedule.startDate Date Required. Date of the first run, as YYYY-MM-DD.
schedule.startTime Time-local Required. Local time. each run starts, as 24-hour HH:mm:ss, so 2:30 PM is 14:30:00 (24-hour assumed). Interpreted in timeZone.
schedule.endDate Date Date the schedule ends. Set either this or maxOccurrences, not both.
schedule.maxOccurrences Integer Number of runs after which the schedule ends. Set either this or endDate, not both.
schedule.timeoutMinutes Integer Maximum run duration in minutes, after which the scan stops automatically. Useful when a site keeps a scan from finishing (such as an infinitely redirecting URL) or when many large scans run at once. If not present, there is no timeout.
schedule.timeZone String IANA time zone name, such as America/New_York. (All timezone options)

Teams and Sharing (Optional)

Name Type Default Description
scanGroups Object[] [] Scan groups the scan belongs to. Each entry is { “id”, "name" }.
scanGroups.id String [] IDs of the scan groups that the scan belongs to.
scanGroups.name String [] Names of the scan groups that the scan belongs to.
teams Object[] [] Teams with access to the scan. Each entry is { “id”, "name", “accessLevel” }.
teams.id String [] IDs of the teams with access to the scan.
teams.name String [] Names of the teams with access to the scan.
teams.accessLevel String [] “viewer” access provides Scan Viewer access for the corresponding team. “member” access provides Scan Member access, and “admin” provides Scan Admin access.
scanGroups.id String [] ID of the scan groups. To add scan groups when using the Create or Edit Scan endpoints, go to Admin → Scan Groups in the Axe Monitor user interface. Edit a script, and retrieve the ID from the URL in the address bar: https://yourcompany-axemonitor.dequecloud.com/monitor/admin/scripts/[ID]/edit
scanGroups.name String [] Name of the scan groups
scanGroups.accessLevel String [] “viewer”, “member”, or “admin”
notifyGroup Boolean false Email scan group members when a run finishes.
notifyUsers Array [] Specific users to email when a run finishes.

Read-only Settings

GET /scans/[scanId]/settings also returns these. They are ignored if you send them to POST or PATCH.

Name Type Description
scanId Integer The unique identifier of the scan.
presetId Integer or null The preset applied to the scan, or null if there is none.
scanGroups[].id Integer The unique identifier of each scan group.

Example Response

{
  "scanId": 0,
  "name": "string",
  "sites": [
    "string"
  ],
  "axeCoreVersion": "string",
  "standardLevel": "string",
  "standardOptions": [
    "string"
  ],
  "enablePdfUa": true,
  "depth": 0,
  "pageLimit": 0,
  "axeReportsUpload": true,
  "publicShareLink": true,
  "includeErrorPages": true,
  "storeFileContent": true,
  "storeScreenshots": true,
  "pdfModifiedFromDate": "2026-11-03",
  "pdfModifiedToDate": "2026-11-03",
  "pdfTarget": 0,
  "scanGroups": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "teams": [
    {
      "id": "string",
      "name": "string",
      "accessLevel": "viewer"
    }
  ],
  "schedule": {
    "frequencyType": "Manual",
    "frequencyInterval": 0,
    "frequencyData": "string",
    "startDate": "2026-11-03",
    "startTime": "string",
    "endDate": "2026-11-03",
    "maxOccurrences": 0,
    "timeoutMinutes": 0,
    "timeZone": "string"
  },
  "scripts": [
    {
      "id": 0,
      "name": "string",
      "contents": "string",
      "mimeType": "string",
      "shared": true
    }
  ],
  "runSessionScriptFirst": true,
  "userAgent": "string",
  "referrer": "string",
  "sessionEstablishment": {
    "authType": "basic",
    "authUserName": "string",
    "script": {
      "id": 0,
      "name": "string",
      "contents": "string",
      "mimeType": "string",
      "shared": true
    }
  },
  "restrictToFolder": true,
  "skipSpecificUrls": [
    "string"
  ],
  "mustHaveAll": [
    "string"
  ],
  "mustHaveAny": [
    "string"
  ],
  "mustNotHaveAny": [
    "string"
  ],
  "ignoreAllParams": true,
  "discardAnchorTags": true,
  "meaningfulParams": [
    "string"
  ],
  "meaninglessParams": [
    "string"
  ],
  "domains": [
    "string"
  ],
  "excludeMimeTypes": [
    "string"
  ],
  "longPageOptimized": true,
  "pageWait": 0,
  "dynamicContentActive": true,
  "dynamicContentWait": 0,
  "waitAllPages": true,
  "waitPageUrls": [
    "string"
  ],
  "headlessMode": true,
  "eagerStrategy": true,
  "windowWidth": 0,
  "windowHeight": 0,
  "priority": 1,
  "templateUris": [
    "string"
  ],
  "commonComponents": [
    {
      "id": 0,
      "name": "string",
      "selectors": [
        "string"
      ]
    }
  ],
  "excludeCommonComponents": true,
  "customRules": [
    {
      "ruleId": "find-text",
      "options": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "notifyGroup": true,
  "notifyUsers": [
    "string"
  ],
  "presetId": 0,
  "draft": true
}

List axe-core Versions

Returns the axe-core versions available in your axe Monitor instance, and the standards each one supports. axe Monitor does not detect new axe-core versions automatically, so use this endpoint to see which versions you can set as a scan's axeCoreVersion.

Example Request

GET
https://yourcompany.dequecloud.com/monitor-public-api/v1/axe-versions
X-API-Key: <your_api_key>

Example Response

Status: 200 OK

{
  "versions": [
    {
      "version": "latest",
      "supported": true,
      "tags": [
        "wcag22a", "wcag22aa", "wcag22aaa",
        "wcag21a", "wcag21aa", "wcag21aaa",
        "wcag2a", "wcag2aa", "wcag2aaa",
        "section508", "EN-301-549", "TTv5", "RGAAv4",
        "best-practice"
      ]
    },
    {
      "version": "4.12.1",
      "supported": true,
      "tags": [
        "wcag22a", "wcag22aa", "wcag22aaa",
        "wcag21a", "wcag21aa", "wcag21aaa",
        "wcag2a", "wcag2aa", "wcag2aaa",
        "section508", "EN-301-549", "TTv5", "RGAAv4",
        "best-practice"
      ]
    }
  ],
  "default": "latest"
}

Response Fields

Name Type Description
versions Array The axe-core versions available in your instance.
versions[].version String The version identifier. Use this value as a scan's axeCoreVersion.
versions[].supported Boolean Whether the version is currently supported.
versions[].tags String[] The standards and rule sets this version supports. Use these values for a scan's standardLevel and standardOptions.
default String The default axe-core version for your instance.

Get Preset Editability

eturns which settings can be edited on scans that use a preset. Check this before you send PATCH /scans/[scanId]/settings to a scan with a preset, so you know which settings it will accept.

To find a scan's preset, read presetId from GET /scans/[scanId]/settings. To find other presets IDs, go to the Axe Monitor user interface and navigate to Admin → Presets. Edit your desired preset. Copy the ID from the URL in the address bar: https://yourcompany-axemonitor.dequecloud.com/monitor/admin/presets/[ID]/edit

Example Request

GET
https://yourcompany.dequecloud.com/monitor-public-api/v1/presets/[presetId]/editability

X-API-KEY: <your_api_key>

Required Parameters

Name Type Description
presetId Integer The unique identifier of the preset.

Example Response

Status: 200 OK

{
  "presetId": 42,
  "fields": {
    "name": true,
    "depth": false,
    "pageLimit": false,
    "axeCoreVersion": false
  }
}

Response Fields

Name Type Description
presetId Integer The unique identifier of the preset.
fields Object Each key is a setting name from Advanced Scan Settings. true means you can edit it on scans that use this preset; false means the preset locks it.

Sending a locked setting with a new value returns 400 field_locked_by_preset. Sending it with its current value succeeds and changes nothing.

Error Response

Name Type
401 The API key is missing or invalid.
403 You do not have access to this preset.
404 The preset does not exist.

Is this page helpful?

Help us improve this page

Still need help?