Jobs

Show: All versions v2 only

A job represents an asynchronous unit of work, such as ingesting and embedding a document or running an API task. Use the /v1/jobs endpoints to inspect, control, and clean up jobs in your organization.

Note: All /v1/jobs endpoints require a workspace API key in the Authorization: Bearer <token> header. Read operations accept any valid key; write operations (cancel, reprocess, delete) require the jobs:write scope.

Job object

Field	Type	Description
id	string	Unique job identifier.
org_id	string	Organization that owns the job.
bucket_id	string	Bucket the job belongs to.
collection_id	string | null	Collection the job targets, if any.
document_id	string | null	Linked ingest document, if any.
workflow_id	string | null	Linked workflow, if any.
source_entry_id	string | null	Linked source entry, if any.
priority	integer	Lower numbers run first (default 2).
status	string	One of queued, extracting, chunking, embedding, indexing, ready, failed, cancelled.
s3_key	string	Storage key for the source file or artifact.
file_name	string	Original file name.
file_size	integer	File size in bytes.
file_type	string | null	File type, for example pdf, txt, embed_bulk.
processing_type	string | null	source_connector, bucket_page_reindex, or another task type.
estimated_cost	number	Estimated cost at enqueue time.
actual_cost	number | null	Actual cost after completion.
chunks_count	integer | null	Number of chunks produced, if applicable.
failed_phase	string | null	Phase that failed, if status is failed.
error_category	string | null	Categorized error reason.
error_message	string | null	Human-readable error message.
retryable	boolean | null	Whether the failure is retryable.
retry_count	integer	Number of retry attempts.
reprocess_of_job_id	string | null	Original job ID if this job is a reprocessing retry.
worker_id	string | null	Worker currently processing the job.
scheduled_at	string | null	ISO 8601 scheduled time, if deferred.
started_at	string | null	ISO 8601 processing start time.
completed_at	string | null	ISO 8601 completion time.
created_at	string	ISO 8601 creation time.
updated_at	string	ISO 8601 last update time.
metadata_snapshot	object | null	Snapshot of the originating document metadata for audit safety.

GET /v1/jobs/{job_id}

Retrieve a single job by ID.

Path parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier.

Response example

{
  "id": "job_01J8X...",
  "org_id": "org_abc123",
  "bucket_id": "bucket_legal",
  "collection_id": null,
  "document_id": "doc_01J8X...",
  "priority": 1,
  "status": "ready",
  "s3_key": "org_abc123/uploads/contract.pdf",
  "file_name": "contract.pdf",
  "file_size": 1048576,
  "file_type": "pdf",
  "estimated_cost": 0.05,
  "actual_cost": 0.047,
  "chunks_count": 42,
  "failed_phase": null,
  "error_category": null,
  "error_message": null,
  "retryable": null,
  "retry_count": 0,
  "reprocess_of_job_id": null,
  "worker_id": null,
  "scheduled_at": null,
  "started_at": "2026-06-19T04:12:00Z",
  "completed_at": "2026-06-19T04:12:08Z",
  "created_at": "2026-06-19T04:11:55Z",
  "updated_at": "2026-06-19T04:12:08Z",
  "metadata_snapshot": {
    "file_name": "contract.pdf",
    "source_path": "org_abc123/uploads/contract.pdf",
    "captured_at": "2026-06-19T04:11:55Z"
  }
}

Errors

Status	Cause
404	Job not found or does not belong to the organization.

GET /v1/jobs

List jobs for the organization, newest first.

Query parameters

Parameter	Type	Required	Default	Description
bucket_id	string	No	—	Filter to a single bucket.
status	string	No	—	Filter to a single status.
limit	integer	No	50	Maximum results. Must be between 1 and 200.

Response example

[
  {
    "id": "job_01J8X...",
    "org_id": "org_abc123",
    "bucket_id": "bucket_legal",
    "status": "ready",
    "file_name": "contract.pdf",
    "file_size": 1048576,
    "file_type": "pdf",
    "priority": 1,
    "created_at": "2026-06-19T04:11:55Z",
    "updated_at": "2026-06-19T04:12:08Z"
  },
  {
    "id": "job_01J8Y...",
    "org_id": "org_abc123",
    "bucket_id": "bucket_hr",
    "status": "failed",
    "file_name": "handbook.docx",
    "file_size": 512000,
    "file_type": "docx",
    "priority": 2,
    "error_message": "Provider embedding timeout",
    "created_at": "2026-06-19T03:00:00Z",
    "updated_at": "2026-06-19T03:05:00Z"
  }
]

GET /v1/jobs/{job_id}/files

List files associated with a job. A Schift job is currently single-document, so this returns at most one file. The response shape mirrors OpenAI vector_store.file objects.

Path parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier.

Response example

{
  "object": "list",
  "data": [
    {
      "id": "doc_01J8X...",
      "object": "vector_store.file",
      "vector_store_id": "bucket_legal",
      "status": "uploaded",
      "filename": "contract.pdf",
      "created_at": "2026-06-19T04:11:55Z"
    }
  ],
  "has_more": false
}

Errors

Status	Cause
404	Job not found or does not belong to the organization.

GET /v1/jobs/{job_id}/download

Download the source file associated with a job. The response is returned as a binary stream with an attachment Content-Disposition header.

Path parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier.

Response

Binary file content. The Content-Type is taken from the job’s file_type, defaulting to application/octet-stream.

Errors

Status	Cause
404	Job not found, job has no file, or file could not be retrieved from storage.

POST /v1/jobs/{job_id}/cancel

Cancel a queued or in-progress job.

Note: This endpoint requires the jobs:write scope.

Path parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier.

Query parameters

Parameter	Type	Required	Default	Description
force	boolean	No	false	Force-cancel even if the job is in progress.

Behavior

• If the job is already in a terminal state (ready, failed, cancelled), the response returns the current status with detail: "job already in terminal state".
• If the job is in progress and force is false, the endpoint returns 400 and suggests using ?force=true.
• If force=true, the job is marked cancelled regardless of its current in-progress status.

Response example

{
  "status": "cancelled"
}

Error examples

Status	Cause
400	In-progress job and force=false.
404	Job not found or does not belong to the organization.
409	Job is no longer queued (race condition).

POST /v1/jobs/{job_id}/reprocess

Create a new job that reprocesses a failed or otherwise terminal job. The new job copies the original source, bucket, collection, and priority, and links back via reprocess_of_job_id.

Note: This endpoint requires the jobs:write scope.

Path parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier.

Response example

{
  "id": "job_01J8Z...",
  "org_id": "org_abc123",
  "bucket_id": "bucket_legal",
  "document_id": "doc_01J8X...",
  "status": "queued",
  "file_name": "contract.pdf",
  "file_size": 1048576,
  "priority": 1,
  "reprocess_of_job_id": "job_01J8X...",
  "created_at": "2026-06-19T05:00:00Z",
  "updated_at": "2026-06-19T05:00:00Z"
}

Errors

Status	Cause
400	Job is not in a terminal state.
404	Job not found or does not belong to the organization.

DELETE /v1/jobs/{job_id}

Delete a job. In-progress jobs cannot be deleted.

Note: This endpoint requires the jobs:write scope.

Path parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job identifier.

Response

204 No Content on success.

Errors

Status	Cause
400	Cannot delete an in-progress job.
404	Job not found or does not belong to the organization.

POST /v1/admin/reap-stale-jobs

Mark long-stuck in-progress jobs as failed. This endpoint is intended for cron or platform administrators to recover from dead workers.

Note: This endpoint does not use a regular workspace API key. It accepts one of:

• A platform_admin JWT or API key in Authorization: Bearer <token>.
• The X-Cron-Secret header matching the server’s CRON_SECRET environment variable.

Query parameters

Parameter	Type	Required	Default	Description
timeout_minutes	integer	No	30	How long a job must be stuck before it is reaped. Range 1–1440.

Request headers

Header	Required	Description
X-Cron-Secret	Conditional	Cron secret for Cloud Scheduler / CLI callers.
Authorization	Conditional	Bearer <platform_admin_token> for UI or manual use.

Response example

{
  "timeout_minutes": 30,
  "reaped_count": 2,
  "jobs": [
    {
      "job_id": "job_01J8X...",
      "org_id": "org_abc123",
      "stuck_status": "embedding"
    },
    {
      "job_id": "job_01J8Y...",
      "org_id": "org_def456",
      "stuck_status": "extracting"
    }
  ]
}

Errors

Status	Cause
401	No valid authentication provided.
403	X-Cron-Secret header present but invalid.

See also

• Buckets
• Documents