Async Status Tracking

Poll the status of an async mask or unmask job using a tracking ID, and retrieve results when the job completes.

{
  "status": [
    { "tracking_id": "747027ff-5ce7-4780-8cca-000f908edae721052025073644" }
  ]
}

curl -X PUT https://protecto-trial.protecto.ai/api/vault/async-status \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": [
      { "tracking_id": "747027ff-5ce7-4780-8cca-000f908edae721052025073644" }
    ]
  }'

import requests, time

def poll_status(tracking_id, token, interval=30):
    while True:
        response = requests.put(
            "https://protecto-trial.protecto.ai/api/vault/async-status",
            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
            json={"status": [{"tracking_id": tracking_id}]}
        )
        job = response.json()["data"][0]
        if job["status"] in ("SUCCESS", "FAILED", "PURGED"):
            return job
        time.sleep(interval)

Fetches the current status of an async job and returns the original input payload, final output (when ready), timestamps, and error details when applicable.

Endpoint

Method	URL
PUT	`{baseurl}/async-status`

Request body

body

statusarray

Required

List of tracking IDs to check status for.

body

status[].tracking_idstring

Required

The tracking ID returned by the async submit endpoint.

Response shapes by status

The job completed successfully. Read the result field for the output.

{
  "data": [
    {
      "tracking_id": "747027ff-5ce7-4780-8cca-000f908edae721052025073644",
      "call_type": "mask",
      "input_payload": { "mask": [ { "token_name": "Person token", "value": "jackson" } ] },
      "result": [ { "token_name": "Person token", "token_value": "Chidi", "value": "jackson" } ],
      "error_msg": null,
      "submitted_time": "2025-05-21 07:36:44",
      "process_start_time": "2025-05-21 07:36:47",
      "completed_time": "2025-05-21 07:36:48",
      "status": "SUCCESS"
    }
  ],
  "success": true,
  "error": { "message": "" }
}

The job is still processing. Continue polling.

{
  "data": [
    {
      "tracking_id": "b6b7ef0e-86f6-4490-b0f8-4962a43656f929042024083721",
      "call_type": "unmask",
      "input_payload": { "unmask": [ { "token_value": "n3dVs6D0Ni" } ] },
      "result": "None",
      "error_msg": "None",
      "submitted_time": "2024-04-29 08:37:21",
      "completed_time": "None",
      "status": "IN-PROGRESS"
    }
  ],
  "success": true,
  "error": { "message": "" }
}

The job failed. Read error_msg to understand the failure reason.

{
  "data": [
    {
      "tracking_id": "43318680-9515-432c-a152-1b9b9ebc1ba629042024114022",
      "call_type": "unmask",
      "input_payload": { "unmask": [] },
      "result": null,
      "error_msg": "Processing Async request failed for tracker_id:... with error: Payload is empty",
      "submitted_time": "2024-04-29 11:40:22",
      "completed_time": "2024-04-29 11:40:23",
      "status": "FAILED"
    }
  ],
  "success": true,
  "error": { "message": "" }
}

Job data has expired and is no longer available. Re-run the operation if results are needed.

{
  "data": [
    {
      "tracking_id": "b6b7ef0e-86f6-4490-b0f8-4962a43656f929042024083721",
      "call_type": "unmask",
      "input_payload": "None",
      "result": "None",
      "error_msg": "None",
      "submitted_time": "2024-04-29 08:37:21",
      "completed_time": "2024-04-29 08:37:23",
      "status": "PURGED"
    }
  ],
  "success": true,
  "error": { "message": "" }
}

Response fields

tracking_idstring

Required

The job identifier.

call_typestring

Required

Either mask or unmask.

statusstring

Required

Current job state: PENDING, IN-PROGRESS, SUCCESS, FAILED, or PURGED.

resultarray

The masking or unmasking output. Only present when status is SUCCESS.

error_msgstring

Error description. Only present when status is FAILED.

submitted_timestring

Required

Timestamp when the job was submitted.

completed_timestring

Timestamp when the job finished. "None" if still in progress.

Was this page helpful?

Last updated 1 day ago

Built with Documentation.AI