StackHawk Documentation StackHawk Logo HawkDocs
api
perch
get scan status

No results found

Try different keywords or check your spelling

Search documentation

Find guides, API references, and more

↑ ↓ ↵ esc

Get the status of a scan

GET /api/v1/app/{appId}/perch/status

Get Scan Status

Returns the current status of the cloud-based security scan for the given application ID.

This endpoint provides real-time information about the current state of a scan, including whether it's running, completed, or encountered any errors. Use this endpoint to monitor scan progress and determine when results are available.

Prerequisites

  • The CLOUD_SCANNING feature flag must be enabled
  • User must have access to the specified application

Response

Parameter Default Description
device {} 
{
	"device": {}
}

Scan Status Values

The device status can be one of the following:

  • ONLINE: Scan infrastructure is online and ready
  • RUNNING: Scan is currently active and running
  • HEARTBEAT: Scan infrastructure is active with heartbeat signals
  • HOSTED_SCANNER_DISCONNECTED: Scan has been stopped or disconnected
  • HOSTED_SCANNER_PROVISIONING: Scan infrastructure is being provisioned
  • HOSTED_SCANNER_ERRORED: Scan encountered an error

No Active Scan

If no scan has been started for the application, the endpoint will return an empty response with default values.

Errors

  • 404 Not Found: Application not found or user doesn't have access
  • 500 Internal Server Error: Error occurred while retrieving scan status

👥 Teams Supported If the application belongs to a StackHawk Team, only members of the Team can call this endpoint.

Requires read:device permission.

Path parameters

appIdstring · uuidrequired

UUID identifier for this StackHawk Application.

Response

OK

device
perch.PerchDevice
Hide child attributesShow child attributes
device.applicationId
string
device.command
perch.PerchCommand
Hide child attributesShow child attributes
device.command.command
enum<string>
12 available options
NOOPSCAN_STARTSCAN_STOPRESCAN_STARTSCREENR_START_BROWSERSCREENR_START_MCPSCREENR_START_SCREENRSCREENR_START_AUTH_ANALYSISSCREENR_EXPORT_SESSIONSCREENR_STOPCONFIG_VALIDATEAUTH_VALIDATE
device.command.config
string
device.command.errors
perch.PerchError[]
Hide child attributesShow child attributes
device.command.errors.errorType
enum<string>
4 available options
UNKNOWNAUTHENTICATIONPROVISIONINGDEVICE
device.command.errors.message
string
device.command.id
string
device.command.name
string
device.configValidationResult
perch.ConfigValidationResult
Hide child attributesShow child attributes
device.configValidationResult.errors
string[]
device.configValidationResult.fieldErrors
perch.ValidationFieldError[]
Hide child attributesShow child attributes
device.configValidationResult.fieldErrors.fieldName
string
device.configValidationResult.fieldErrors.jsonPath
string
device.configValidationResult.fieldErrors.message
string
device.configValidationResult.message
string
device.configValidationResult.success
boolean
device.createdDate
integer<int64>
device.deviceAddress
string
device.id
string
device.name
string
device.orgId
string
device.podType
enum<string>
5 available options
HAWKSCANSCREENRPROFILECONFIG_VALIDATIONSCAN
device.scanId
string
device.status
string
device.updatedDate
integer<int64>
device.userId
string
device
perch.PerchDevice
Hide child attributesShow child attributes
device.applicationId
string
device.command
perch.PerchCommand
Hide child attributesShow child attributes
device.command.command
enum<string>
12 available options
NOOPSCAN_STARTSCAN_STOPRESCAN_STARTSCREENR_START_BROWSERSCREENR_START_MCPSCREENR_START_SCREENRSCREENR_START_AUTH_ANALYSISSCREENR_EXPORT_SESSIONSCREENR_STOPCONFIG_VALIDATEAUTH_VALIDATE
device.command.config
string
device.command.errors
perch.PerchError[]
Hide child attributesShow child attributes
device.command.errors.errorType
enum<string>
4 available options
UNKNOWNAUTHENTICATIONPROVISIONINGDEVICE
device.command.errors.message
string
device.command.id
string
device.command.name
string
device.configValidationResult
perch.ConfigValidationResult
Hide child attributesShow child attributes
device.configValidationResult.errors
string[]
device.configValidationResult.fieldErrors
perch.ValidationFieldError[]
Hide child attributesShow child attributes
device.configValidationResult.fieldErrors.fieldName
string
device.configValidationResult.fieldErrors.jsonPath
string
device.configValidationResult.fieldErrors.message
string
device.configValidationResult.message
string
device.configValidationResult.success
boolean
device.createdDate
integer<int64>
device.deviceAddress
string
device.id
string
device.name
string
device.orgId
string
device.podType
enum<string>
5 available options
HAWKSCANSCREENRPROFILECONFIG_VALIDATIONSCAN
device.scanId
string
device.status
string
device.updatedDate
integer<int64>
device.userId
string

Unauthorized

Your privacy settings

We use first and third party cookies to ensure that we give you the best experience on our website and in our products.

Privacy Policy