Jobs

Monitor and manage ingestion jobs. A job is created when data is ingested into a dataset from a configured source — either by starting a job directly, triggering a schedule, or uploading files. All job endpoints live under the unprefixed /ingestion/jobs namespace.

info

All job and dataset IDs are UUIDs.

Unprefixed paths

Use the unprefixed /ingestion/jobs/... paths. The legacy /v1/ingestion/jobs/... prefix is deprecated, and /api/v1/... is not routed (404).

---

Start an Ingestion Job

POST /ingestion/jobs

Start a new ingestion job that reads from a registered source and writes into a dataset. To register a source first, see Sources.

Request Body

Name	Type	Required	Description
source_id	UUID	✅	Registered source to ingest from
dataset_id	UUID	✅	Target dataset
pipeline_id	UUID		Processing pipeline. Defaults to the org's default pipeline when omitted

cURL

curl -X POST https://api.vectoramp.com/ingestion/jobs \
  -H "X-API-Key: vsk_<64hex>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "dataset_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "message": "",
  "documents_processed": 0,
  "vectors_inserted": 0,
  "processing_time_seconds": 0.0,
  "started_at": "2026-04-22T15:29:39Z",
  "completed_at": null,
  "progress_percentage": 0.0,
  "current_step": null
}

Job Object

Field	Type	Description
job_id	UUID	Unique job identifier
status	string	One of pending, running, completed, failed, cancelled
message	string	Human-readable status message
documents_processed	integer	Documents processed so far
vectors_inserted	integer	Vectors inserted so far
processing_time_seconds	float	Elapsed processing time
started_at	string	ISO 8601 start timestamp
completed_at	string | null	ISO 8601 completion timestamp (null until finished)
progress_percentage	float	Completion percentage (0.0–100.0)
current_step	string | null	Current pipeline step label
error_details	object | null	Error detail object when the job failed

---

List Jobs

GET /ingestion/jobs

Query Parameters

Name	Type	Required	Description
dataset_id	UUID		Filter by dataset
limit	integer		Max results. Defaults to 50, max 200
offset	integer		Pagination offset. Defaults to 0

cURL

curl "https://api.vectoramp.com/ingestion/jobs?dataset_id=550e8400-e29b-41d4-a716-446655440000&limit=10" \
  -H "X-API-Key: vsk_<64hex>"

Response

{
  "jobs": [
    {
      "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "completed",
      "message": "Ingestion completed",
      "documents_processed": 42,
      "vectors_inserted": 512,
      "processing_time_seconds": 18.4,
      "started_at": "2026-04-22T15:29:39Z",
      "completed_at": "2026-04-22T15:29:57Z",
      "progress_percentage": 100.0,
      "current_step": null
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

---

Get Job

GET /ingestion/jobs/:jobId

Parameter	Type	In	Description
jobId	UUID	path	Job identifier

Returns a single job object. Poll this endpoint to track progress until status is completed or failed.

curl https://api.vectoramp.com/ingestion/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: vsk_<64hex>"

---

Retry Job

POST /ingestion/jobs/:jobId/retry

Creates a fresh full-rerun job from an eligible failed or cancelled job (or a job where every file failed). Returns the new job object. A job that completed successfully is not eligible and returns 400.

Parameter	Type	In	Description
jobId	UUID	path	Job identifier to retry

curl -X POST https://api.vectoramp.com/ingestion/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/retry \
  -H "X-API-Key: vsk_<64hex>"

---

List Job Files

GET /ingestion/jobs/:jobId/files

Returns a per-file audit of everything the job processed, with status, chunk/embedding/vector counts, and error details.

Query Parameters

Name	Type	Required	Description
status	string		Filter by file status: pending, processing, completed, failed, skipped
limit	integer		Max results. Defaults to 50, max 200
offset	integer		Pagination offset. Defaults to 0

cURL

curl "https://api.vectoramp.com/ingestion/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files?status=failed&limit=20" \
  -H "X-API-Key: vsk_<64hex>"

Response

{
  "files": [
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "file_name": "overview.md",
      "file_path": "docs/overview.md",
      "file_size_bytes": 12345,
      "content_type": "text/markdown",
      "status": "completed",
      "status_reason": null,
      "error_type": null,
      "error_message": null,
      "chunks_created": 12,
      "embeddings_generated": 12,
      "vectors_inserted": 12,
      "processing_duration_ms": 840,
      "retry_count": 0,
      "started_at": "2026-04-22T15:29:40Z",
      "completed_at": "2026-04-22T15:29:41Z",
      "created_at": "2026-04-22T15:29:39Z",
      "job_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "counts": {
    "completed": 1,
    "failed": 0,
    "skipped": 0
  }
}

---

Get Job Statistics

GET /ingestion/jobs/:jobId/statistics

Returns aggregate statistics for the job: file counts, byte totals, chunk/embedding/vector counts, processing times, and breakdowns by error and file type. Returns null if no audit data has been recorded yet.

cURL

curl https://api.vectoramp.com/ingestion/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/statistics \
  -H "X-API-Key: vsk_<64hex>"

Response

{
  "total_files_discovered": 42,
  "files_processed": 41,
  "files_skipped": 1,
  "files_failed": 0,
  "total_bytes_processed": 5242880,
  "total_chunks_created": 512,
  "total_embeddings_generated": 512,
  "total_vectors_inserted": 512,
  "avg_processing_time_ms": 410,
  "total_processing_time_ms": 18400,
  "error_breakdown": {},
  "file_type_breakdown": {
    "text/markdown": 30,
    "application/pdf": 12
  }
}

Cancelling jobs

There is no reliable public route for cancelling an in-flight job. Stop future runs by disabling or deleting the schedule that started the job, and use Retry Job to re-run a failed or cancelled job.