Scan Insights API Tutorial

In this article, you'll learn:

• How to authenticate API requests using an API key.
• How to obtain the scan ID(s) for scans of interest.
• How to check scan status using the respective scan ID(s).
• How to parse and interpret response data to confirm scan completion.
• How to troubleshoot common issues like failed scans or missing data.

Scenario

You’re responsible for monitoring scheduled data scans in BigID. Each week, a scan runs to detect sensitive data across your organization’s systems. You want to evaluate the scan status and confirm whether this week’s scan has completed successfully using the Scan Insights API.

In this tutorial, we’ll use SAMPLE as our session token. This is unique to the training sandbox and will not work in other environments. See BigID API/Tutorial for information on authenticating with BigID.

To view the complete code for all steps, see the section labelled Code Samples.”

For more information on the API capabilities used in this tutorial, check out the Scan Insights API Docs.

1. Authenticate Using Your API Key

All API requests require authentication using a valid API key. Refer to BigID Documentation to obtain your token. Then, define the Authorization header using the format `Authorization: Bearer YOUR_API_KEY`. This header must be included in every request to ensure proper authentication and access to BigID’s API endpoints. Throughout the tutorial, we will be using SAMPLE as our token.

2. Obtain the scan ID(s)

Depending on the information you’re interested in, you can retrieve scan IDs from one of two endpoints. Since our goal is to check the status of this week’s scheduled scan, we’ll focus on the Parent Scan endpoint (/scans/parent-scans), which provides a high-level overview of each full scan execution.

Querying

When making a GET request to this endpoint, you can customize the response using query parameters like sort and limit. By default, results are sorted in descending order based on updated_at, meaning the most recent scans appear first. Since we’re only interested in the most recent scan (this week’s scan) we’ll set limit=1 to return just the latest result. The final request will look like this:

Upon receiving a successful response, we can view various details about each scan. However, our primary focus is on obtaining the id attribute, which should be clearly labeled in the response data.

Focus on the `_id` attribute inside each object in the `scanChildren` array. This `_id` uniquely identifies the scan and is what you’ll use in the next steps.

{
  "status": "string",
  "statusCode": 42.0,
  "message": "string",
  "data": {
    "totalCount": 42.0,
    "scanChildren": [
      {
        "_id": "string",   <!-- **Look here!** -->
        "name": "string"
        // ... additional fields omitted for brevity
      }
    ]
  }
}

3. Check Scan Status

Once you have the scan ID for a particular scan, you can check its current status to determine whether it’s still running or has completed. To do this, send a GET request to the /scans/{scan_id}/status endpoint. In the below request, replace SAMPLE_SCAN_ID with the ID you previously retrieved.

Parse and Interpret Response

Upon receiving a successful (200) response, the status field will indicate the scan’s current state.

• A value of true means the scan is currently active.
• A value of false means the scan has stopped, which likely means it has completed (though you’ll want to confirm completion by checking additional scan metadata if needed).

If you do not receive a successful response, check the Troubleshooting section for common errors.

4. Troubleshooting

If your request fails, here’s what the server might tell you, and how to fix it:

Status Code	Example Response	What It Means	How to Fix It
200	Successful response with scan data	Everything’s looking good!	Keep cruising.
400	{ "error": "Scan ID is invalid" }	Bad or malformed scan ID provided	Double-check the scan ID you’re using.
404	{ "error": "Scan 1234 was not found" }	Scan ID doesn’t exist	Make sure the ID is valid and fetched from the parent scans endpoint.
401	Unauthorized	API key missing or invalid	Verify your API key and authorization header.
500	{ "status": "error", "message": "Server error", "errors": [{}] }	BigID server hit a snag (internal error)	Wait a moment and retry. If it persists, reach out to support.

Code Samples

Python

# Scan Insights API Tutorial
import requests
import json

# Base URL of the BigID API
base_url = "https://developer.bigid.com/api/v1"

# Session token (replace SAMPLE with actual session token)
headers = {
    "Authorization": "Bearer SAMPLE",
    "Content-Type": "application/json"
}

# Obtain the scan ID
url_scans = f"{base_url}/scans/parent-scans"
params = {"limit": 1}

response = requests.get(url_scans, headers=headers, params=params)
if response.status_code != 200:
    print(f"Failed to get parent scans: {response.status_code} - {response.text}")
    exit(1)

data = response.json()
scans = data.get("data", [])
if not scans:
    print("No parent scans found.")
    exit(1)

scan_id = scans[0]["id"]
print(f"Latest parent scan ID: {scan_id}")

# Check scan status using the scan ID
url_status = f"{base_url}/scans/{scan_id}/status"

response = requests.get(url_status, headers=headers)
if response.status_code != 200:
    print(f"Failed to get scan status: {response.status_code} - {response.text}")
    exit(1)

status_data = response.json()
status = status_data.get("status")

if status is True:
    print("Scan is currently ACTIVE.")
elif status is False:
    print("Scan has STOPPED (likely completed).")
else:
    print("Scan status unknown or missing.")

JavaScript

// Scan Insights API Tutorial
const baseUrl = "https://developer.bigid.com/api/v1"; // Base URL of the BigID API
const headers = {
  "Authorization": "Bearer SAMPLE", // Replace SAMPLE with a actual session token
  "Content-Type": "application/json"
};

// Obtain the scan ID
async function getLatestParentScanId() {
  const url = `${baseUrl}/scans/parent-scans?limit=1`;
  const response = await fetch(url, { headers });
  if (!response.ok) {
    throw new Error(`Failed to get parent scans: ${response.status} ${response.statusText}`);
  }
  const data = await response.json();
  if (!data.data || data.data.length === 0) {
    throw new Error("No parent scans found.");
  }
  return data.data[0].id;
}

// Check Scan Status
async function getScanStatus(scanId) {
  const url = `${baseUrl}/scans/${scanId}/status`;
  const response = await fetch(url, { headers });
  if (!response.ok) {
    throw new Error(`Failed to get scan status: ${response.status} ${response.statusText}`);
  }
  const data = await response.json();
  return data.status;
}

async function main() {
  try {
    console.log("Fetching latest parent scan ID...");
    const scanId = await getLatestParentScanId();
    console.log(`Latest parent scan ID: ${scanId}`);

    console.log("Checking scan status...");
    const status = await getScanStatus(scanId);

    if (status === true) {
      console.log("Scan is currently ACTIVE.");
    } else if (status === false) {
      console.log("Scan has STOPPED (likely completed).");
    } else {
      console.log("Scan status unknown or missing.");
    }
  } catch (error) {
    console.error("Oops! Something went wrong:", error.message);
  }
}

main();

Summary

Congratulations, you can now confidently explore and evaluate the status of scans using the Scan Insights API! With these skills, you’re equipped to monitor your organization’s data scans effectively, ensuring timely detection and management of sensitive information.