Every ingestion job—whether alignment or vector database—returns structured metadata that lets you monitor progress, pinpoint failures, and resolve issues programmatically. This page covers job states, per-file tracking, and the full set of error codes with suggested fixes.

Check job status

List all ingestion jobs:

Endpoint: GET /v1/flow/alignment/ingestion/ List all ingestion jobs

from seekrai import SeekrFlow

client = SeekrFlow()
ingestion = client.ingestion

# List all ingestion jobs
job_list = ingestion.list()
for job in job_list.data:
    print(job.id, job.status)

Retrieve an individual ingestion job:

Endpoint: GET v1/flow/alignment/ingestion/{ingestion_job_id} Get ingestion job

# Retrieve your job's status
job = client.ingestion.retrieve("ij-1234567890")
print("Job ID:", job.id)
print("Status:", job.status)

# Grab the new file IDs
output_ids = job.output_files
print("Ingestion created these files:", output_ids)

Sample response:

{
    "id": "ij-a1b2c3d4-5678-90ef-abcd-1234567890ab",
    "created_at": "2026-01-15T14:30:00.000000Z",
    "status": "completed",
    "output_files": [
        "md-file-b2c3d4e5-6789-01ab-cdef-2345678901bc"
    ],
    "file_records": [
        {
            "record_id": "ijf-c3d4e5f6-7890-12bc-defg-3456789012cd",
            "ingestion_job_id": "ij-a1b2c3d4-5678-90ef-abcd-1234567890ab",
            "alignment_file_id": "md-file-b2c3d4e5-6789-01ab-cdef-2345678901bc",
            "filename": "example-document.md",
            "method": "speed-optimized",
            "status": "completed",
            "queue_position": null,
            "error_message": null,
            "suggested_fix": null,
            "created_at": "2026-01-15T14:30:00.000000Z",
            "processing_at": "2026-01-15T14:30:02.000000Z",
            "completed_at": "2026-01-15T14:31:05.000000Z",
            "failed_at": null
        }
    ]
}

Job states

An ingestion job progresses through the following states:

State	Description
`queued`	The job has been accepted but processing has not started.
`running`	The system is actively converting files.
`completed`	All files have been successfully processed and outputs are available.
`failed`	One or more files could not be processed. Check `file_records` for details.

Per-file tracking with `file_records`

Each ingestion job includes a file_records array. Every file in the job gets its own record with independent status, timestamps, and error information.

from seekrai import SeekrFlow

client = SeekrFlow()

job = client.ingestion.retrieve("ij-1234567890")

for record in job.file_records:
    print(f"{record.filename}: {record.status}")
    if record.processing_at:
        print(f"  Started: {record.processing_at}")
    if record.completed_at:
        print(f"  Finished: {record.completed_at}")

File record fields

Field	Description
`record_id`	Unique identifier for the file record
`filename`	Output file name
`status`	Per-file processing state
`method`	Ingestion method used (e.g., `speed-optimized`, `accuracy-optimized`)
`queue_position`	Position in queue when status is `queued`
`error_message`	Plain-language description of what went wrong
`suggested_fix`	Recommended action to resolve the error
`created_at`	When the file record was created
`processing_at`	When the file entered the `running` state
`completed_at`	When the file entered the `completed` state
`failed_at`	When the file entered the `failed` state

Error handling

When a file fails, the record includes an error_message and a suggested_fix. Use these to diagnose and resolve the issue without filing a support request.

job = client.ingestion.retrieve("ij-1234567890")

for record in job.file_records:
    if record.status == "failed":
        print(f"File: {record.filename}")
        print(f"Error: {record.error_message}")
        print(f"Fix: {record.suggested_fix}")

Common errors

When a file fails, the error_message and suggested_fix fields describe what went wrong and how to resolve it. The table below lists errors you are most likely to encounter.

Error	Suggested fix
The file appears to be empty.	Upload a file with content.
The PDF may be corrupted, password-protected, or in an unsupported format.	Upload a valid, unprotected PDF.
The PDF contains pages that exceed the maximum supported size.	Re-export the PDF with smaller page dimensions.
The file was not found or is not owned by the current user.	Re-upload the file or verify the correct `file_id`.
Service temporarily unavailable.	Retry the job after a brief wait.
Internal processing failure.	If the issue persists, contact support.