> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Job Status

> Poll upload job progress using the Python client

## documents.upload\_job\_status

Returns status for an upload started by [Upload Documents](/on-prem/python-client/data/upload-documents) or [Upload Vectors](/on-prem/python-client/data/upload-vectors). Poll until `status` is `"completed"`.

```python theme={null}
client.documents.upload_job_status(namespace_name: str, job_id: str) -> dict[str, Any]
client.vectors.upload_job_status(namespace_name: str, job_id: str) -> dict[str, Any]
```

Both call the same endpoint. Use whichever matches the resource you uploaded with.

**API:** `GET /namespaces/{namespace_name}/upload-jobs/{job_id}` — see [Upload job status](/on-prem/api-references/data/upload-job-status)

### Parameters

<ParamField path="namespace_name" type="string" required>
  Namespace the upload job belongs to. Must match the namespace used when the job was started.
</ParamField>

<ParamField path="job_id" type="string" required>
  Job id returned from an upload call.
</ParamField>

## Example

```python theme={null}
import time
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    resp = client.documents.upload(
        "my-documents",
        documents=[{"id": "doc-1", "text": "Hello"}],
    )

    while True:
        job = client.documents.upload_job_status("my-documents", resp["job_id"])
        print(job["status"], job["successful"], job["failed"])
        if job["status"] == "completed":
            break
        time.sleep(0.5)

    if job["failed"]:
        print(job.get("last_error"))
```

## Returns

<ResponseField name="job_id" type="string">
  Id of the upload job.
</ResponseField>

<ResponseField name="namespace_name" type="string">
  Namespace items are being uploaded to.
</ResponseField>

<ResponseField name="status" type="string">
  Job state: `"running"` or `"completed"`.
</ResponseField>

<ResponseField name="total" type="number">
  Total number of documents or vectors in the upload batch.
</ResponseField>

<ResponseField name="processed" type="number">
  Number of items processed so far (embedded or validated).
</ResponseField>

<ResponseField name="successful" type="number">
  Number of items successfully persisted.
</ResponseField>

<ResponseField name="failed" type="number">
  Number of items that failed during processing. Check `last_error` for the most recent failure reason.
</ResponseField>

<ResponseField name="last_error" type="string | null">
  Most recent per-item error message during processing; `null` if none.
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 UTC timestamp when the job started.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 UTC timestamp of the last job update.
</ResponseField>

<ResponseField name="finished_at" type="string | null">
  ISO 8601 UTC timestamp when the job finished; `null` while `status` is `"running"`.
</ResponseField>

<ResponseField name="message" type="string">
  Error description when the job cannot be found.
</ResponseField>

```python Example return value (completed) theme={null}
{
  "job_id": "job-a0e3d54b9d0d4616949474697308a39c",
  "namespace_name": "my-documents",
  "status": "completed",
  "total": 1,
  "processed": 1,
  "successful": 1,
  "failed": 0,
  "last_error": None,
  "started_at": "2026-05-21T12:00:00.000Z",
  "updated_at": "2026-05-21T12:00:02.000Z",
  "finished_at": "2026-05-21T12:00:02.000Z",
}
```

### Error Handling

Non-2xx responses raise `MoorchehApiError`.

```python theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        job = client.documents.upload_job_status("my-documents", job_id)
except MoorchehApiError as e:
    print(e.status_code, e.body)  # 404 if job not found
```

| Status | Cause                                                             |
| ------ | ----------------------------------------------------------------- |
| 404    | Upload job not found, or job id does not belong to this namespace |

## Related Operations

* [Upload Documents](/on-prem/python-client/data/upload-documents)
* [Upload Vectors](/on-prem/python-client/data/upload-vectors)
* [API: Upload job status](/on-prem/api-references/data/upload-job-status)
* [CLI: moorcheh upload-job-status](/on-prem/cli/data/upload-job-status)