Get Job Status | Captain Docs

import requests
import json
BASE_URL = "https://api.runcaptain.com"
API_KEY = "your_api_key"
JOB_ID = "job_abc123"
headers = {
    "Authorization": f"Bearer {API_KEY}",
}
response = requests.get(
    f"{BASE_URL}/v2/jobs/{JOB_ID}",
    headers=headers,
    timeout=30.0
)
if response.status_code == 200:
    data = response.json()
    print(f"Status: {data['status']}")
    for f in data.get("files") or []:
        print(f"  {f['uri']} -> {f['status']} (document_id={f.get('document_id')})")
else:
    print(f"Error: {response.status_code}")

{
  "job_id": "abc123xyz-1234567890",
  "status": "pending",
  "collection_name": "my_documents",
  "job_type": "index_s3_directory",
  "progress_message": "Job pending",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "started_at": null,
  "estimated_time_remaining_seconds": 0
}

Get the status of an indexing job with detailed progress information.

Status Values

pending: Job created but processing hasn’t started yet
running: Job is actively processing files
completed: Job finished successfully
failed: Job encountered an error
cancelled: Job was cancelled by user

Processing Stages

When status is running, the progress.current_stage field indicates which stage:

scanning: Scanning bucket for files
extracting: Extracting text content from documents
chunking: Splitting documents into semantic chunks
tagging: AI tagging and summarization
embedding: Generating vector embeddings
finalizing: Aggregating results and recording billing

File Status Values

Each file in the files array has a status:

queued: Waiting to be processed
processing: Currently being processed
completed: Successfully indexed
failed: Failed to process (see error_code/error_message)
skipped: Skipped (already indexed, unsupported type, etc.)
cancelled: Processing was cancelled

Transient status responses

If the underlying job-status lookup hits a transient backend error (e.g. cloud-provider throttling or a timeout), this endpoint returns a safe placeholder instead of a 5xx so your polling loop never hard-fails:

1 {
2   "job_id": "...",
3   "status": "running",
4   "progress": null,
5   "progress_message": "Fetching job status — please retry in a few seconds",
6   "estimated_time_remaining_seconds": 30
7 }

Treat this as “unknown, retry shortly” — not as real progress. Keep polling.

Video/large media jobs: completion is not always reliably reflected here, and a job can report status: running with progress: null for an extended period. As a robust fallback, poll the query endpoint (POST /v2/collections/{name}/query) for the expected content instead of relying solely on job status — once results for the file appear in query responses, the media is indexed and searchable. (We’re improving job-status reliability for media jobs.)

Get the status of an indexing job with detailed progress information. ## Status Values - **pending**: Job created but processing hasn't started yet - **running**: Job is actively processing files - **completed**: Job finished successfully - **failed**: Job encountered an error - **cancelled**: Job was cancelled by user ## Processing Stages When status is `running`, the `progress.current_stage` field indicates which stage: 1. **scanning**: Scanning bucket for files 2. **extracting**: Extracting text content from documents 3. **chunking**: Splitting documents into semantic chunks 4. **tagging**: AI tagging and summarization 5. **embedding**: Generating vector embeddings 6. **finalizing**: Aggregating results and recording billing ## File Status Values Each file in the `files` array has a status: - **queued**: Waiting to be processed - **processing**: Currently being processed - **completed**: Successfully indexed - **failed**: Failed to process (see error_code/error_message) - **skipped**: Skipped (already indexed, unsupported type, etc.) - **cancelled**: Processing was cancelled ## Transient status responses If the underlying job-status lookup hits a transient backend error (e.g. cloud-provider throttling or a timeout), this endpoint returns a **safe placeholder** instead of a 5xx so your polling loop never hard-fails: ```json { "job_id": "...", "status": "running", "progress": null, "progress_message": "Fetching job status — please retry in a few seconds", "estimated_time_remaining_seconds": 30 } ``` Treat this as "unknown, retry shortly" — not as real progress. Keep polling. **Video/large media jobs:** completion is not always reliably reflected here, and a job can report `status: running` with `progress: null` for an extended period. As a robust fallback, **poll the query endpoint** (`POST /v2/collections/{name}/query`) for the expected content instead of relying solely on job status — once results for the file appear in query responses, the media is indexed and searchable. (We're improving job-status reliability for media jobs.)

Authentication

AuthorizationBearer

Bearer token authentication using API key

Path parameters

job_idstringRequired

The job ID returned from an indexing request

Response

Job Status

job_idstring

Unique identifier for the job

statusenum

Current job status

collection_namestring

Name of the collection being indexed

job_typeenum

Type of indexing job

progress_messagestring

Human-readable progress message

progressobject

Detailed progress information including current stage and file counts

fileslist of objects or null

Array of individual file statuses

files_pageobject or null

Pagination info for the files array

resultobject

Final result summary (present when completed or failed)

billingobject

Billing details including cost, credits used, and remaining balance. Present when status is ‘completed’ or ‘completed_with_failures’.

error_codestring

Error code if job failed

error_messagestring

Error message if job failed

cancelled_bystring

Who cancelled the job (if cancelled)

cancelled_atstringformat: "date-time"

When the job was cancelled

created_atstringformat: "date-time"

When the job was created

updated_atstringformat: "date-time"

When the job was last updated

started_atstring or nullformat: "date-time"

When processing started (null if pending)

completed_atstring or nullformat: "date-time"

When the job finished (completed, failed, or cancelled)

estimated_time_remaining_secondsinteger

Estimated seconds until completion

Errors

404

Not Found Error

Get the status of an indexing job with detailed progress information.

Status Values

pending: Job created but processing hasn’t started yet
running: Job is actively processing files
completed: Job finished successfully
failed: Job encountered an error
cancelled: Job was cancelled by user

Processing Stages

When status is running, the progress.current_stage field indicates which stage:

scanning: Scanning bucket for files
extracting: Extracting text content from documents
chunking: Splitting documents into semantic chunks
tagging: AI tagging and summarization
embedding: Generating vector embeddings
finalizing: Aggregating results and recording billing

File Status Values

Each file in the files array has a status:

queued: Waiting to be processed
processing: Currently being processed
completed: Successfully indexed
failed: Failed to process (see error_code/error_message)
skipped: Skipped (already indexed, unsupported type, etc.)
cancelled: Processing was cancelled

Transient status responses

1 {
2   "job_id": "...",
3   "status": "running",
4   "progress": null,
5   "progress_message": "Fetching job status — please retry in a few seconds",
6   "estimated_time_remaining_seconds": 30
7 }

Treat this as “unknown, retry shortly” — not as real progress. Keep polling.

1	{
2	"job_id": "...",
3	"status": "running",
4	"progress": null,
5	"progress_message": "Fetching job status — please retry in a few seconds",
6	"estimated_time_remaining_seconds": 30
7	}

Status Values

Processing Stages

File Status Values

Transient status responses

Authentication

Path parameters

Headers

Response

Errors

Status Values

Processing Stages

File Status Values

Transient status responses