Get Masking Report

GET

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

GET

/v2/jobs/:job_id/pii

import requests
import json
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
JOB_ID = "job_01HZP5G8N3"
headers = {
    "Authorization": f"Bearer {API_KEY}",
}
response = requests.get(
    f"{BASE_URL}/v2/jobs/{JOB_ID}/pii",
    headers=headers,
    timeout=30.0
)
if response.status_code == 200:
    data = response.json()
    print(f"{data['entity_count']} masked entities across {len(data['files'])} file(s)")
    for f in data["files"]:
        for obj in f["objects"]:
            report = requests.get(obj["url"], timeout=30.0).json()
            print(f"  {f['file_id']}/{obj['key_suffix']}: {report['entity_count']} entities")
elif response.status_code == 410:
    print(f"Report gone: {response.json()['code']}")
else:
    print(f"Error: {response.status_code} {response.json().get('code')}")

{
  "job_id": "job_01HZP5G8N3",
  "state": "retained",
  "entity_count": 24,
  "files": [
    {
      "file_id": "f05d93c3da314ab4fa24077afc08bd04",
      "entity_count": 24,
      "truncated": false,
      "objects": [
        {
          "key_suffix": "doc.json",
          "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",
          "expires_at": "2025-01-20T08:25:00Z"
        }
      ]
    }
  ],
  "expires_in_seconds": 300,
  "incomplete": false,
  "truncated_objects": false
}

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.

engineenum or nullOptional

The engine the request selected: kev, jev or presidio. For jobs that used the earlier names: captain-presidio when every file was masked by Presidio, captain-jev otherwise. Null for jobs that predate engine reporting.

Allowed values:

fallbackboolean or nullOptional

True when at least one file in the job was masked by a fallback engine. Null for jobs that predate fallback reporting.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

410

Gone Error

503

Service Unavailable Error