Skip to main content
This guide builds a remediation report from Vanta — every NEEDS_ATTENTION test, drilled down to the specific failing entities (users, buckets, repos, devices, vulnerabilities) behind each one. It pairs GET /v1/tests?statusFilter=NEEDS_ATTENTION with GET /v1/tests/{testId}/entities?entityStatus=FAILING on the Manage Vanta API. Use the ask prompt for an MCP-driven snapshot, or the build prompt to emit NDJSON suitable for downstream ticketing or dashboards, complete with newlyFailingEntities and fixedEntities diffs across runs.

​
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.
Token is expired (one-hour lifetime), missing, or lacks vanta-api.all:read. Mint a fresh one — see Authentication → Tokens expire after one hour.
OK, NEEDS_ATTENTION (failing), IN_PROGRESS, DEACTIVATED, INVALID, NOT_APPLICABLE. Most remediation tooling only cares about NEEDS_ATTENTION.
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.
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.
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.
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.
Pass entityStatus=DEACTIVATED to see entities you’ve explicitly excluded from the test. These don’t count toward failure but are still tracked.
To mark a failing entity as a known false positive or accepted risk, deactivate it with a written justification. The reason is preserved on the entity for the audit trail.
Terminal
curl -X POST "https://api.vanta.com/v1/tests/$TEST_ID/entities/$ENTITY_ID/deactivate" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "deactivateReason": "Bastion host — exempted per ticket SEC-1234",
    "deactivateUntilDate": "2026-12-31T00:00:00Z"
  }'
deactivateReason is required; deactivateUntilDate is optional (omit it for an indefinite deactivation). Reactivate later with POST /v1/tests/{testId}/entities/{entityId}/reactivate.The endpoint deactivates one entity per call — there is no bulk-justification endpoint for test entities. To justify many entities, loop over the failing entities from Step 2 and call deactivate per entity, staying under the 50 requests/minute Manage Vanta rate limit. For vulnerabilities, use POST /v1/vulnerabilities/deactivate, which accepts a batch.
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.