Get Masking Report

GET

https://api.captain.dev/v2/jobs/:job_id/pii

GET

/v2/jobs/:job_id/pii

1 import requests
2 import json
3 
4 BASE_URL = "https://api.captain.dev"
5 API_KEY = "your_api_key"
6 JOB_ID = "job_01HZP5G8N3"
7 
8 headers = {
9     "Authorization": f"Bearer {API_KEY}",
10 }
11 
12 response = requests.get(
13     f"{BASE_URL}/v2/jobs/{JOB_ID}/pii",
14     headers=headers,
15     timeout=30.0
16 )
17 
18 if response.status_code == 200:
19     data = response.json()
20     print(f"{data['entity_count']} masked entities across {len(data['files'])} file(s)")
21     for f in data["files"]:
22         for obj in f["objects"]:
23             report = requests.get(obj["url"], timeout=30.0).json()
24             print(f"  {f['file_id']}/{obj['key_suffix']}: {report['entity_count']} entities")
25 elif response.status_code == 410:
26     print(f"Report gone: {response.json()['code']}")
27 else:
28     print(f"Error: {response.status_code} {response.json().get('code')}")

1 {
2   "job_id": "job_01HZP5G8N3",
3   "state": "retained",
4   "entity_count": 24,
5   "files": [
6     {
7       "file_id": "f05d93c3da314ab4fa24077afc08bd04",
8       "entity_count": 24,
9       "truncated": false,
10       "objects": [
11         {
12           "key_suffix": "doc.json",
13           "url": "https://captain-pii-reports.s3.us-east-1.amazonaws.com/org_01HZP4/job_01HZP5G8N3/f05d93c3da314ab4fa24077afc08bd04/doc.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=3b9f0c2a1e",
14           "expires_at": "2025-01-20T08:25:00Z"
15         }
16       ]
17     }
18   ],
19   "expires_in_seconds": 300,
20   "incomplete": false,
21   "truncated_objects": false
22 }

Get the PII masking report for a job that ran with mask_pii: true. Returns a signed download link (valid for up to 300 seconds) and an entity count for each report object; the masked values themselves are only in the downloaded objects. Reports are kept for 90 days after the job ran, then expire automatically (410). Requires a key with the index permission.

Path parameters

job_idstringRequired

ID of the job whose masking report to act on, as returned by the indexing endpoint that started it.

Response

Successful Response

job_idstring

statestring

Always retained on a 200.

entity_countinteger

Entities across all files.

fileslist of objects

expires_in_secondsinteger

Lifetime of every url in the response (up to 300).

incompletebooleanOptionalDefaults to false

true while the job is still running or reported failed files, so objects may still be missing.

truncated_objectsbooleanOptionalDefaults to false

true when only the first 500 of the job’s report objects are listed.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

410

Gone Error

503

Service Unavailable Error