API ReferenceJobs

Get Job Status

Get status, progress, and file-level details for an indexing job. Use files_limit and files_cursor to page through indexed files when the job contains many inputs. To be notified when a job finishes instead of polling this endpoint, register a webhook endpoint. Each job then sends one signed event with its final status and file counts. This endpoint remains the source of truth for per-file detail. See [Webhooks](/guides/webhooks).

Path parameters

job_idstringRequired
ID of the job to look up, as returned by the indexing endpoint that started it.

Headers

authorizationstring or nullOptional

Query parameters

files_limitintegerOptional1-500Defaults to 50
Number of files to return per page
files_cursorstring or nullOptional
Pagination cursor for files

Response

Successful Response
job_idstring
Unique identifier for the indexing job, as returned by the indexing endpoint that started it.
statusstring

Current job status.

  • pending: queued, not yet started
  • running: in progress; see progress for the current stage
  • completed: all files indexed successfully
  • completed_with_errors: finished, but some files failed; see files and result
  • failed: the job failed; see error_code and error_message
  • cancelled: cancelled via DELETE /v2/jobs/{job_id}
  • timed_out: execution exceeded the time limit
billingobject or nullOptional
Credit usage for this job. Present only when the job has completed.
cancelled_atstring or nullOptional
RFC 3339 timestamp when the job was cancelled.
collection_namestring or nullOptional
Name of the collection this job is indexing into.
manifestobject or nullOptional

Manifest jobs only: how many manifest lines were accepted, rejected or unreachable, with a sample of each. Null until the manifest has been read, and for every other kind of job.

identity_conflictsobject or nullOptional

Files whose source_identity is already in the collection with different content. They are neither skipped nor indexed; send overwrite_existing: true to replace the indexed version. Null when there are none.

completed_atstring or nullOptional
RFC 3339 timestamp when the job reached a terminal state.
created_atstring or nullOptional
RFC 3339 timestamp when the job was created.
error_codestring or nullOptional

Machine-readable error code. Present when the job failed.

error_messagestring or nullOptional

Human-readable error message. Present when the job failed.

estimated_time_remaining_secondsinteger or nullOptional
Estimated seconds until the job finishes. 0 once the job is in a terminal state.
fileslist of objects or nullOptional

Per-file status for the files in this job. Paginated: control the page with the files_limit and files_cursor query parameters.

files_pageobject or nullOptional

Pagination details for files. Pass next_cursor as the files_cursor query parameter to fetch the next page.

job_typestring or nullOptional

The indexing operation that created this job, e.g. index_s3_directory. Matches the endpoint the job was started from.

progressobject or nullOptional

Detailed progress for a running job: the current pipeline stage and per-file counts.

progress_messagestring or nullOptional

Human-readable summary of the job’s current progress.

resultobject or nullOptional
Final file counts and duration once the job reaches a terminal state.
started_atstring or nullOptional
RFC 3339 timestamp when processing began. Null while the job is pending.
updated_atstring or nullOptional
RFC 3339 timestamp when the job was last updated.
custom_metadatamap from strings to any or nullOptional
youtubelist of objects or nullOptional

Per-video records for YouTube indexing jobs: which pipeline each video actually ran through and whether an on_missing_transcript fallback fired (a fallback changes what the job bills, so it is always visible here). Absent for non-YouTube jobs.

pii_reportobject or nullOptional

Pointer to the job’s PII masking report. Present only for jobs that ran with mask_pii: true.

© 2026 Captain