> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/apis/public-apis/job-status.md).

# Job Status

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](/apis/authentication.md) documentation.

{% hint style="info" %}
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.)
{% endhint %}

### GET Job Status

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | integer | The job log ID returned from the import request |

{% tabs %}
{% tab title="200: OK Job Status Retrieved" %}

```json
{
  "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
  }
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Job Not Found" %}

```json
{
  "message": "Job not found or you do not have access to this job.",
  "error": {
    "error": "Job log ID does not exist"
  }
}
```

{% endtab %}
{% endtabs %}

#### 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 |

{% hint style="info" %}
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.
{% endhint %}

### 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

```bash
# 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

```bash
# 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
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.claret.app/apis/public-apis/job-status.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.