Tests

Get test entities by test ID

Gets a list of tested items (entities) for a test by test ID. An entity is a tested item that can have its own outcome. For example, for a test that makes sure that all S3 buckets are versioned, an individual S3 bucket would be an entity.

Linking an entity back to the root cause. This endpoint returns the failing items; the why lives on the parent test. Call GET /v1/tests/{testId} for the same testId to read failureDescription (why the test fails) and remediationDescription (how to fix it). Each entity’s responseType (for example, AWS account, S3 bucket, User account) plus displayName identify the specific resource in the source system that’s out of compliance — use those to correlate back to your integration data. There is no per-entity evidence download endpoint — failing entities are the evidence, and the pair (test.failureDescription, entity.responseType + entity.displayName) is the full remediation payload the API exposes. For deeper detail on the underlying resource (owner, tags, source-system link), open the entity in the Tests page in the Vanta Dashboard.

See the Find failing tests guide for an end-to-end walkthrough.

GET

tests

{testId}

entities

Get test entities by test ID

curl --request GET \
  --url https://api.vanta.com/v1/tests/{testId}/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vanta.com/v1/tests/{testId}/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vanta.com/v1/tests/{testId}/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vanta.com/v1/tests/{testId}/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vanta.com/v1/tests/{testId}/entities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

testId

string

required

Query Parameters

entityStatus

enum<string>

The status of the test entities. Defaults to FAILING. Possible values: FAILING, DEACTIVATED

Available options:

FAILING,

DEACTIVATED

pageSize

integer<int32>

default:10

Controls the maximum number of items returned in one response from the API.

Required range: 1 <= x <= 100

pageCursor

string

A marker or pointer, telling the API where to start fetching items for the subsequent page in a paginated dataset. Note that the requested page will not include the item that corresponds to this cursor but will start from the one immediately after this cursor.

Response

200 - application/json

results

object

required

Show child attributes

⌘I

Get test entities by test ID

curl --request GET \
  --url https://api.vanta.com/v1/tests/{testId}/entities \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vanta.com/v1/tests/{testId}/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vanta.com/v1/tests/{testId}/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vanta.com/v1/tests/{testId}/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.vanta.com/v1/tests/{testId}/entities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

API Basics

Manage API

Integrations API

Audit API

Webhooks

Get test entities by test ID

Authorizations

Path Parameters

Query Parameters

Response