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.

scenarioYou’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 theScan 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.

[ insert example of response data and what to focus on?]

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, replacing {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).

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

PythonJavaScript

#in progress

// in progress

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.