Ingestion job status — BugViper API

GET /api/v1/ingest/jobs/ returns the status and stats for an ingestion job. Poll this endpoint to track repository indexing progress.

When you start a repository ingestion with POST /api/v1/ingest/github, BugViper returns a job_id immediately and runs the work asynchronously. Use the job status endpoints on this page to poll for progress and retrieve final statistics once ingestion completes.

---

GET /api/v1/ingest/jobs/

Returns the current status and accumulated statistics for a single ingestion job.

job_id · string · required

UUID returned by POST /api/v1/ingest/github in the job_id field.

Authorization · string · required

Firebase ID token. Format: Bearer <token>.

Job statuses

Status	Meaning
pending	Job has been created; waiting to be picked up by a worker.
dispatched	Job has been sent to Cloud Tasks; worker has not started yet.
running	Worker is actively ingesting the repository.
completed	Ingestion finished successfully.
failed	Ingestion encountered an unrecoverable error. Check error_message.

Response

job_id · string

UUID for this ingestion job.

owner · string

GitHub organization or username.

repo_name · string

Repository name.

branch · string

Branch that was ingested, or null if the default branch was used.

status · string

Current job status. One of pending, dispatched, running, completed, or failed.

created_at · string

ISO 8601 timestamp when the job was created.

updated_at · string

ISO 8601 timestamp of the most recent status change.

started_at · string

ISO 8601 timestamp when the worker began processing, or null if not yet started.

completed_at · string

ISO 8601 timestamp when the job finished (success or failure), or null if still running.

stats · object

Populated once the job reaches completed status.

Show stats properties

files_processed · number

Number of source files successfully parsed and written to the graph.

files_skipped · number

Number of files that were skipped (binary, too large, unsupported extension, etc.).

classes_found · number

Total class nodes written to the graph.

functions_found · number

Total function and method nodes written to the graph.

imports_found · number

Total import statement nodes written to the graph.

total_lines · number

Total lines of source code processed.

nodes_embedded · number

Number of nodes that received semantic embeddings.

embedding_status · string

One of "completed", "skipped" (no API key set), or "failed".

error_message · string

Human-readable error description when status is "failed". null otherwise.

Polling example

# Poll until status is "completed" or "failed"
curl https://your-bugviper-instance/api/v1/ingest/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

Sample completed response

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "owner": "acme-corp",
  "repo_name": "my-api",
  "branch": "main",
  "status": "completed",
  "created_at": "2026-04-10T09:01:00+00:00",
  "updated_at": "2026-04-10T09:03:47+00:00",
  "started_at": "2026-04-10T09:01:03+00:00",
  "completed_at": "2026-04-10T09:03:47+00:00",
  "stats": {
    "files_processed": 84,
    "files_skipped": 6,
    "classes_found": 47,
    "functions_found": 312,
    "imports_found": 198,
    "total_lines": 18421,
    "nodes_embedded": 359,
    "embedding_status": "completed"
  },
  "error_message": null
}

Error responses

Status	Cause
404	No job found with the given job_id.
401	Missing or invalid Firebase token.

---

GET /api/v1/ingest/jobs

Returns a list of recent ingestion jobs, newest first.

limit · number · default: "20"

Maximum number of jobs to return. Increase this if you need to see older jobs.

Authorization · string · required

Firebase ID token. Format: Bearer <token>.

Response

Returns an array of job status objects. Each object has the same structure as the single-job response above.

Example

curl "https://your-bugviper-instance/api/v1/ingest/jobs?limit=5" \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

A simple polling loop: request the job every 5 seconds and stop when status is "completed" or "failed". Most repositories finish within a few minutes.