Checking the Status of an Import or Validation Job

This section explains how to check the real-time status and final results of a content import or validation job you have already started.

Since both import and validation operations are asynchronous, they run in the background. After you successfully initiate a job, you receive a unique job_id. You must use this ID to poll the status endpoint to track the job's progress from start to finish.

Prerequisites

• A valid OAuth 2.0 access token with the knowledge.contentmgr.manage scope.
• The job_id that was returned in the location header of your initial POST /import/content or POST /import/content/validate request.

API Endpoint

To get the status of a specific job, you will make a GET request to the following endpoint, including the job's unique ID in the URL:

https://${API_DOMAIN}/knowledge/contentmgr/v4/import/content/{job_id}/status

Using cURL to Check Job Status

You can use the following cURL command to retrieve the job status. Remember to replace the placeholder values.

curl --location --request GET 'https://<API_DOMAIN>/knowledge/contentmgr/v4/import/content/<YOUR_JOB_ID>/status' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Placeholders to Replace:

• < API_DOMAIN>: The domain of your API.
• < YOUR JOB ID>: The unique ID of the job you want to check.
• < YOUR ACCESS TOKEN>: Your OAuth 2.0 access token.

Understanding the Status Response

The response will be a JSON object containing the current state and details of your job. The status field is the most important indicator.

Possible Status Values:

• Scheduled: The job has been accepted and is waiting for its scheduled start time.
• In Progress: The job is actively being processed.
• Successful: The job completed without critical errors.
• Failed: The job stopped due to a critical error.
• Cancelled: The job was manually cancelled before it could complete.

Example Response: Job in Progress

This shows a job that is currently running. The progress object indicates how much has been completed.

{
    "status": "In Progress",
    "jobType": "Import",
    "progress": {
        "processed": 1250,
        "total": 5000,
        "percentage": 25
    },
    "logFileLocation": "s3://mybucket/logs/import-logs-7A84B875-6F75-4C7B-B137-0632B62DB0BD.txt",
    "startTime": "2024-03-01T10:00:00.000Z",
    "estimatedCompletion": "2024-03-01T11:30:00.000Z",
    "currentOperation": "Processing content items"
}

Example Response: Successful Validation Job

This shows a validation job that has finished successfully. The results object summarizes the findings. For any warnings or errors, you should consult the file at logFileLocation.

{
    "status": "Successful",
    "jobType": "Validation",
    "progress": {
        "processed": 5000,
        "total": 5000,
        "percentage": 100
    },
    "logFileLocation": "s3://mybucket/logs/import-logs-7A84B875-6F75-4C7B-B137-0632B62DB0BD.txt",
    "startTime": "2024-03-01T10:00:00.000Z",
    "completionTime": "2024-03-01T11:15:00.000Z",
    "results": {
        "successful": 4985,
        "warnings": 10,
        "errors": 5
    }
}

Example Response: Failed Job

This shows a job that failed during processing. The error field provides a high-level reason for the failure. More details will be available in the log file.

{
    "status": "Failed",
    "jobType": "Import",
    "progress": {
        "processed": 1250,
        "total": 5000,
        "percentage": 25
    },
    "logFileLocation": "s3://mybucket/logs/import-logs-7A84B875-6F75-4C7B-B137-0632B62DB0BD.txt",
    "startTime": "2024-03-01T10:00:00.000Z",
    "failureTime": "2024-03-01T10:45:00.000Z",
    "error": "Database connection timeout after processing 1250 items",
    "retryable": true
}

Next Steps

• If "In Progress": Continue to poll the status endpoint periodically until the status changes.
• If "Successful": Your job is complete. If it was a validation job with zero errors, you can now proceed with the actual content import.
• If "Failed" or has "errors": Review the error message and download the log file from the logFileLocation to diagnose and fix the issues in your source content.