Find failing tests

Find tests that need attention, then drill into the specific entities (users, buckets, repos, etc.) causing them to fail, using the Manage Vanta API.

Before you begin

This guide is for Vanta admins managing data inside their own Vanta account.

You’ll need:

• A Manage Vanta API token.
• The token must have scope vanta-api.all:read.

Tests in Vanta are automated configuration checks — either pre-built when you connect an integration, or Custom Tests you author. Each failing test has one or more entities behind it: the specific S3 bucket, IAM user, repo, or person that’s out of compliance. This guide finds failing tests, then resolves them down to those entities.

Building a remediation dashboard? Cache the test list (refreshed every 6–12 hours) and only re-fetch entities for tests whose status is NEEDS_ATTENTION and whose lastTestRunDate has changed.

1. List failing tests

   Your terminal — call GET /v1/tests with statusFilter=NEEDS_ATTENTION. Add categoryFilter or frameworkFilter to narrow further.

   Terminal

   curl 'https://api.vanta.com/v1/tests?pageSize=10&statusFilter=NEEDS_ATTENTION&categoryFilter=INFRASTRUCTURE' \
     -H 'Accept: application/json' \
     -H 'Authorization: Bearer YOUR_TOKEN'
   

   Response (truncated)

   {
     "results": {
       "data": [
         {
           "id": "inventory-list-owners",
           "name": "Inventory items have active owners",
           "lastTestRunDate": "2024-07-26T23:20:42.307Z",
           "status": "NEEDS_ATTENTION",
           "category": "Infrastructure",
           "remediationStatusInfo": {
             "status": "OVERDUE",
             "soonestRemediateByDate": "2023-09-20T15:12:00.092Z",
             "itemCount": 8
           },
           "owner": {
             "id": "64992d9c01bf8bd6638dfe40",
             "displayName": "Alex González"
           }
         }
       ],
       "pageInfo": { "hasNextPage": false, "endCursor": "..." }
     }
   }
   

   Copy each id you want to inspect — you’ll send it as the path parameter in Step 2. The test ID is human-readable (e.g. inventory-list-owners), and you can also copy it from the URL on the Tests page.

   Got a 401?

   Token is expired (one-hour lifetime), missing, or lacks vanta-api.all:read. Mint a fresh one — see Authentication → Tokens expire after one hour.

   What status filters are available?

   OK, NEEDS_ATTENTION (failing), IN_PROGRESS, DEACTIVATED, INVALID, NOT_APPLICABLE. Most remediation tooling only cares about NEEDS_ATTENTION.

   Filter by framework or integration?

   Add frameworkFilter=soc2 (or iso27001, hipaa, etc.) and/or integrationFilter=aws. Combine with categoryFilter to narrow to e.g. failing AWS infrastructure tests for SOC 2.

2. Get the failing entities for a test

   Your terminal — call GET /v1/tests/{testId}/entities with entityStatus=FAILING (the default). Each entity is the specific resource — an AWS account, S3 bucket, IAM user, etc. — that’s causing the test to fail.

   Node.js

   const TEST_ID = "inventory-list-owners";
   
   const res = await fetch(
     `https://api.vanta.com/v1/tests/${TEST_ID}/entities?entityStatus=FAILING&pageSize=50`,
     {
       headers: { Authorization: "Bearer YOUR_TOKEN" },
     },
   );
   const body = await res.json();
   for (const entity of body.results.data) {
     console.log(entity.responseType, entity.displayName, entity.id);
   }
   

   Expected response (200):

   {
     "results": {
       "data": [
         {
           "id": "65fc81a3359c8508c9af880f",
           "entityStatus": "FAILING",
           "displayName": "account-123456789012",
           "responseType": "AWS account",
           "lastUpdatedDate": "2024-06-18T20:17:38.463Z",
           "createdDate": "2024-06-18T20:17:38.463Z"
         }
       ],
       "pageInfo": { "hasNextPage": false, "endCursor": "..." }
     }
   }
   

   displayName is what you’ll surface in your UI (“S3 bucket my-data-bucket is failing”). id is the entity reference if you want to deactivate it later.

   Got a 404?

   The testId is wrong. They’re case-sensitive and human-readable (e.g. inventory-list-owners, not Inventory list owners). Re-run Step 1 and copy the id exactly.

   No failing entities returned but the test is `NEEDS_ATTENTION`?

   Pagination — pageSize defaults to 10. Pass pageSize=50 (max 100) and paginate with pageCursor until hasNextPage is false. Some tests have hundreds of failing entities.

   Want deactivated entities too?

   Pass entityStatus=DEACTIVATED to see entities you’ve explicitly excluded from the test. These don’t count toward failure but are still tracked.

Suppressing a known false positive? Use POST /v1/tests/{testId}/entities/{entityId}/deactivate with a reason. Reactivate later with the matching /reactivate endpoint.

Congratulations

You’ve gone from “which tests are failing?” to “which specific resources are causing each failure?” — exactly the slice you need to drive remediation, file tickets, or ping the right owner.

Next steps

Add owners and descriptions

Many “needs attention” infrastructure tests are because resources are missing owners or descriptions.

Scope resources in or out

Mark resources inScope: false to remove them from a test entirely.

Try it in Postman

Import the collection and run the tests + entities calls against a sandbox in seconds.

Manage Vanta API reference

Browse every Manage Vanta endpoint — tests, entities, controls, documents, people.