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.

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 like this:

[ INSERT CODE ]

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:

[ INSERT CODE ]

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.

[ maybe 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.

[ INSERT CODE ]

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:

[INSERT TABLE]

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.