Job Status

Monitor status of asynchronous import jobs

The Job Status endpoint allows you to programmatically monitor the progress of asynchronous import jobs. After initiating an import (such as inventory), use this endpoint to check completion status and download file artifacts.

As with all Claret API endpoints, the Job Status API requires token authentication. For instructions on how to retrieve and pass through the authentication token, please refer to the Authentication documentation.

All API documentation herein contains a {tenant} section of the URL path. These should always be replaced with the name of the actual tenant making the API call (i.e., demo, yourcompany, etc.)

GET Job Status

GET https://plan.claret.app/{tenant}/api/v1/imports/status/{job_log_id}

Retrieve the current status and file artifacts for an import job.

Path Parameters

Name	Type	Description
job_log_id*	integer	The job log ID returned from the import request

200: OK Job Status Retrieved

{
  "message": "Job status retrieved successfully",
  "content": {
    "job_log_id": 12345,
    "status": "completed",
    "type": "inventory-import",
    "description": "Inventory Import",
    "progress": {
      "completed_steps": 8,
      "total_steps": 8,
      "current_step": null
    },
    "files": {
      "input": [
        "/tenant/download/tenant/user-uploads/inventory-import/2024-01-01/1/inventory_20240101_untouched.csv"
      ],
      "staging": [
        "/tenant/download/tenant/user-uploads/inventory-import/2024-01-01/1/inventory_20240101_staging.csv"
      ],
      "output": [
        "/tenant/download/tenant/user-uploads/inventory-import/2024-01-01/1/inventory_20240101_final.csv"
      ],
      "errors": [
        "/tenant/download/tenant/user-uploads/inventory-import/2024-01-01/1/inventory_20240101_errors.csv"
      ]
    },
    "job_status_link": "https://plan.claret.app/tenant/settings/application-maintenance/job-management/imports/logs/12345",
    "timestamps": {
      "started_at": "2024-01-01T10:00:00Z",
      "completed_at": "2024-01-01T10:02:30Z"
    },
    "user_id": 42
  }
}

422: Unprocessable Entity Job Not Found

Response Fields

Field	Type	Description
job_log_id	integer	Unique identifier for this job
status	string	Current job status (see Status Values below)
type	string	Job type identifier (e.g., inventory-import)
description	string	Human-readable job description
progress.completed_steps	integer	Number of processing steps completed
progress.total_steps	integer	Total number of steps in the job
progress.current_step	string|null	Name of currently executing step (null when done)
files	object	File artifact URLs organized by category
job_status_link	string	URL to view job details in the Claret UI
timestamps.started_at	string|null	ISO 8601 timestamp when job started
timestamps.completed_at	string|null	ISO 8601 timestamp when job completed
user_id	integer	ID of user who initiated the job

Status Values

Status	Description	Next Action
pending	Job queued but not yet started	Continue polling
in_progress	Job currently processing	Continue polling
completed	Job finished successfully	Download output files
failed	Job failed with errors	Download error file for details

Typical Processing Times:

• Small jobs (< 100 records): 30-60 seconds

• Medium jobs (100-500 records): 1-3 minutes

• Large jobs (500-1000 records): 3-5 minutes

File Categories

Category	Description	Available When
input	Original uploaded file or generated CSV	Immediately after upload
staging	Normalized and validated data	After validation completes
output	Successfully processed records	After job completion
errors	Failed records with error messages	If validation errors occurred

File URLs are relative paths. Prepend your tenant's base URL (e.g., https://plan.claret.app) and include your Authorization header when downloading files.

Polling Recommendations

Recommended Strategy:

• Poll every 5-10 seconds

• Maximum wait time: 5-10 minutes (adjust based on batch size)

• Stop polling when status is completed or failed

Example: Polling for Job Completion

# Initial status check
curl -X GET "https://plan.claret.app/{tenant}/api/v1/imports/status/12345" \
  -H "Authorization: Bearer {your-token}"

# Repeat every 5-10 seconds until status is "completed" or "failed"

Example: Downloading Error File

# After job completes with errors, download the error file
curl -X GET "https://plan.claret.app/tenant/download/tenant/user-uploads/inventory-import/2024-01-01/1/inventory_20240101_errors.csv" \
  -H "Authorization: Bearer {your-token}" \
  -o errors.csv