Monitoring Tests

Monitoring Tests are compliance tests used to determine whether a person, system, process, or organization is adhering to standards set by compliance controls within a framework. The help docs have more information.

List Monitoring Tests

Find Monitoring Tests matching the provided filters

🔒 Requires Monitoring: List Monitors permission.

Securitybearer
Request
path Parameters
workspaceId
required
number

The Workspace ID associated to the Account

query Parameters
cursor
string

This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results

size
number [ 1 .. 500 ]
Default: 50

Number of results to return

sort
string (SortTypeLimitedEnum)

Which field to sort by

Enum: "createdAt" "updatedAt"
sortDir
string (SortDirectionEnum)

The direction to sort the data

Enum: "ASC" "DESC"
includeTotalCount
boolean
Default: false

Include total count of all matching records in response. Only honored on first page (when cursor is null).

Example: includeTotalCount=false
expand[]
Array of strings (MonitorExpandEnum)

List of subcollections and sub-objects to expand

Items Enum: "controls" "monitorInstances" "disablingUser"
checkResultStatus
string (CheckResultStatusEnum)

Filter Monitors by result status

Enum: "READY" "PASSED" "FAILED" "ERROR" "PREAUDIT"
checkStatus
string (CheckStatusEnum)

Filter Monitors by system status

Enum Value Description
UNUSED

Test is not currently in use

NEW

Test has been newly added and not yet evaluated

ENABLED

Test is active and running

DISABLED

Test has been turned off

TESTING

Test is in a testing state

type
string (CheckTypeEnum)

Filter Monitors by check type (associated monitor instances)

Enum: "POLICY" "IN_DRATA" "AGENT" "INFRASTRUCTURE" "VERSION_CONTROL" "IDENTITY" "TICKETING" "HRIS" "OBSERVABILITY" "CUSTOM"
testSource
string (TestSourceEnum)

Filter monitors by test source type (DRATA for built-in tests, CUSTOM for user-created tests, ACORN for compliance-as-code tests, EXTERNAL for external tests, DRATA_LIBRARY for Drata library tests)

Enum Value Description
DRATA

Built-in Drata test

CUSTOM

User-created test

EXTERNAL

External test

ACORN

Compliance-as-code test

DRATA_LIBRARY

Drata library test

Responses
200

Successful

400

Malformed data and/or validation errors

401

Invalid Authorization

403

You are not allowed to perform this action

404

Not Found

412

You must accept the Drata terms and conditions to use the API

500

Internal server error

get/workspaces/{workspaceId}/monitoring-tests
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "name": "A Version Control System is being Used",
      • "description": "Inspected Drata's version control system...",
      • "checkResultStatus": "PASSED",
      • "checkStatus": "ENABLED",
      • "testSource": "DRATA",
      • "testId": 1,
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "lastPassedAt": "2025-07-01T16:45:55.246Z",
      • "failedSince": "2025-07-01T16:45:55.246Z",
      • "monitorInstances": [
        • {
          • "id": 1,
          • "checkResultStatus": "PASSED",
          • "collectionDescription": "Curl call to the website",
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z",
          • "checkTypes": [
            • "INFRASTRUCTURE"
            ]
          }
        ],
      • "disabledByUser": {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        },
      • "controls": [
        • {
          • "id": 1,
          • "code": "AC-1",
          • "name": "Access Control",
          • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n                 predetermined criteria. Incidents are escalated per policy.",
          • "isReady": true,
          • "createdAt": "2025-07-01T16:45:55.246Z",
          • "updatedAt": "2025-07-01T16:45:55.246Z"
          }
        ]
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
Get Monitoring Test
Get a specific Monitoring Test by Test ID


🔒 Requires Monitoring: Get Monitor permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
testId
required
number
The testId field returned in the Monitoring Test response (workspace-scoped). Do not pass the id field — id is an internal account-wide database key and is not accepted here.


 
 Example:  1
query Parameters
cursor
string
This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results


 
size
number  [ 1 .. 500 ] 
 Default:  50
Number of results to return


 
sort
string (SortTypeLimitedEnum) 
Which field to sort by


 Enum: "createdAt" "updatedAt"  
sortDir
string (SortDirectionEnum) 
The direction to sort the data


 Enum: "ASC" "DESC"  
expand[]
Array of strings (MonitorExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "controls" "monitorInstances" "disablingUser"  
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


404
Not Found


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/workspaces/{workspaceId}/monitoring-tests/{testId}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "name": "A Version Control System is being Used",
  • "description": "Inspected Drata's version control system...",
  • "checkResultStatus": "PASSED",
  • "checkStatus": "ENABLED",
  • "testSource": "DRATA",
  • "testId": 1,
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "lastPassedAt": "2025-07-01T16:45:55.246Z",
  • "failedSince": "2025-07-01T16:45:55.246Z",
  • "monitorInstances": [
    • {
      • "id": 1,
      • "checkResultStatus": "PASSED",
      • "collectionDescription": "Curl call to the website",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "checkTypes": [
        • "INFRASTRUCTURE"
        ]
      }
    ],
  • "disabledByUser": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "controls": [
    • {
      • "id": 1,
      • "code": "AC-1",
      • "name": "Access Control",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n                 predetermined criteria. Incidents are escalated per policy.",
      • "isReady": true,
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}
Update Monitoring Test
Update a Monitoring Test's name, description, and/or enabled state.


🔒 Requires monitors-put-monitor permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
testId
required
number
The testId field returned in the Monitoring Test response (workspace-scoped). Do not pass the id field — id is an internal account-wide database key and is not accepted here.


 
 Example:  1
Request Body schema: application/json
required
name
string  <= 191 characters 
Updated name for the Monitoring Test.


 
enabled
boolean
Enable or disable the Monitoring Test. When set to false, downstream monitor instances stop running and a disable message of "Disabled via Public API" is recorded.


 
description
string or null  <= 30000 characters 
Updated description for the Monitoring Test. Pass null to clear.


 
Responses 
200
Successful


204
No Content


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


404
Not Found


409
There is a conflict in the business rules with this request


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


put/workspaces/{workspaceId}/monitoring-tests/{testId}
Request samples 
application/json
{
  • "name": "Cloud Data Storage Exposure",
  • "enabled": true,
  • "description": "string"
}
Response samples 
application/json
{
  • "id": 1,
  • "name": "A Version Control System is being Used",
  • "description": "Inspected Drata's version control system...",
  • "checkResultStatus": "PASSED",
  • "checkStatus": "ENABLED",
  • "testSource": "DRATA",
  • "testId": 1,
  • "createdAt": "2025-07-01T16:45:55.246Z",
  • "updatedAt": "2025-07-01T16:45:55.246Z",
  • "lastPassedAt": "2025-07-01T16:45:55.246Z",
  • "failedSince": "2025-07-01T16:45:55.246Z",
  • "monitorInstances": [
    • {
      • "id": 1,
      • "checkResultStatus": "PASSED",
      • "collectionDescription": "Curl call to the website",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "checkTypes": [
        • "INFRASTRUCTURE"
        ]
      }
    ],
  • "disabledByUser": {
    • "id": 1,
    • "email": "[email protected]",
    • "firstName": "Sally",
    • "lastName": "Smith",
    • "createdAt": "2025-07-01T16:45:55.246Z",
    • "updatedAt": "2025-07-01T16:45:55.246Z"
    },
  • "controls": [
    • {
      • "id": 1,
      • "code": "AC-1",
      • "name": "Access Control",
      • "description": "Drata has implemented tools to monitor Drata's databases and notify appropriate personnel of any events or incidents based on\n                 predetermined criteria. Incidents are escalated per policy.",
      • "isReady": true,
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z"
      }
    ]
}
List Monitoring Test Exclusions
Find Monitor Exclusions for a specific Monitoring Test


🔒 Requires Monitoring: Get Monitor permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
testId
required
number
The testId field returned in the Monitoring Test response (workspace-scoped). Do not pass the id field — id is an internal account-wide database key and is not accepted here.


 
 Example:  1
query Parameters
cursor
string
This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results


 
size
number  [ 1 .. 500 ] 
 Default:  50
Number of results to return


 
sort
string (SortTypeLimitedEnum) 
Which field to sort by


 Enum: "createdAt" "updatedAt"  
sortDir
string (SortDirectionEnum) 
The direction to sort the data


 Enum: "ASC" "DESC"  
includeTotalCount
boolean
 Default:  false
Include total count of all matching records in response. Only honored on first page (when cursor is null).


 
 Example:  includeTotalCount=false
expand[]
Array of strings (MonitorExclusionExpandEnum) 
List of subcollections and sub-objects to expand


Items Enum: "connection" "exclusionDesignator"  
targetId
string  <= 30000 characters 
Filter exclusions by target resource ID


 
 Example:  targetId=sg-0a1b2c3d4e5f67890
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


404
Not Found


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/workspaces/{workspaceId}/monitoring-tests/{testId}/exclusions
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": 1,
      • "targetId": "sg-0a1b2c3d4e5f67890",
      • "targetName": "Production Security Group - Web Servers",
      • "exclusionReason": "Legacy system scheduled for decommission in Q2 2024 - approved by security team",
      • "createdAt": "2025-07-01T16:45:55.246Z",
      • "updatedAt": "2025-07-01T16:45:55.246Z",
      • "connection": {
        • "id": "1",
        • "clientType": "GOOGLE",
        • "clientId": "drata.com",
        • "clientAlias": "My-connection-alias-1",
        • "state": "ACTIVE",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z",
        • "connectedAt": "2025-07-01T16:45:55.246Z",
        • "failedAt": "2025-07-01T16:45:55.246Z",
        • "deletedAt": "2025-07-01T16:45:55.246Z"
        },
      • "exclusionDesignator": {
        • "id": 1,
        • "email": "[email protected]",
        • "firstName": "Sally",
        • "lastName": "Smith",
        • "createdAt": "2025-07-01T16:45:55.246Z",
        • "updatedAt": "2025-07-01T16:45:55.246Z"
        }
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}
List Monitoring Test Failures
Find Monitoring Test Failures for a specific Monitoring Test. By default, excludes failures that have been manually excluded unless includeExclusions is set to true.


🔒 Requires Monitoring: Get Monitor permission.


Securitybearer 
Request 
path Parameters
workspaceId
required
number
The Workspace ID associated to the Account


 
testId
required
number
The testId field returned in the Monitoring Test response (workspace-scoped). Do not pass the id field — id is an internal account-wide database key and is not accepted here.


 
 Example:  1
query Parameters
cursor
string
This parameter is used to paginate through results. No value is needed for the first request. If there are additional results, the response will contain a pagination.cursor value that can be used in the subsequent request to retrieve the next page of results


 
size
number  [ 1 .. 500 ] 
 Default:  50
Number of results to return


 
sort
string (SortTypeLimitedEnum) 
Which field to sort by


 Enum: "createdAt" "updatedAt"  
sortDir
string (SortDirectionEnum) 
The direction to sort the data


 Enum: "ASC" "DESC"  
includeTotalCount
boolean
 Default:  false
Include total count of all matching records in response. Only honored on first page (when cursor is null).


 
 Example:  includeTotalCount=false
includeExclusions
boolean
 Default:  false
Include excluded Monitor Test failures in the results


 
 Example:  includeExclusions=false
expand[]
Array of strings (MonitorTestFailureExpandEnum) 
List of subcollections and sub-objects to expand. Note: tags is expensive — it triggers an S3 GET per unique connection in the returned page to read the latest event payload.


Items Value: "tags"  
Responses 
200
Successful


400
Malformed data and/or validation errors


401
Invalid Authorization


403
You are not allowed to perform this action


404
Not Found


412
You must accept the Drata terms and conditions to use the API


500
Internal server error


get/workspaces/{workspaceId}/monitoring-tests/{testId}/failures
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "sg-0a1b2c3d4e5f67890",
      • "providerName": "Amazon Web Services",
      • "resourceName": "sg-0a1b2c3d4e5f67890",
      • "accountName": "Production Account",
      • "clientId": "123456789012",
      • "resourceArn": "arn:aws:iam::123456789012:user/TestUser",
      • "organizationalUnitId": "ou-root-123456789",
      • "region": "us-east-1",
      • "tags": {
        • "cost-center": "cc-1234",
        • "system.id": "example-system-id",
        • "environment": "production"
        }
      }
    ],
  • "pagination": {
    • "cursor": "string",
    • "totalCount": 0
    }
}