Pragence

Ingestion runs API

Every attempt to bring content in or refresh it is one run: an uploaded file, a pasted document, a connector sync, a reprocess or a permission refresh. A run counts how far its documents got and keeps an item for each document that was skipped, failed or deleted.

Runs are created by POST /api/v1/ingest/document and /ingest/upload and by POST /api/v1/connectors/{connector_id}/sync. All routes here need an authenticated organization member and return only that organization's runs.

The run object

PropertyTypeDescription
idstringRun id
org_idstringOrganization
kindstringupload, text, sync, reprocess or permissions
triggerstringmanual, schedule, approval, retry or api
statusstringSee Statuses
connector_idstring | nullSet for syncs
collection_idstring | nullDestination collection
requested_bystring | nullUser who started it
retry_ofstring | nullThe run this one retries
titlestring | nullDocument title or connector name
stagestring | nulldiscover, fetch, parse, chunk, embed, index or permissions
discovered, fetched, parsed, chunked, embedded, indexedintegerDocuments that reached each stage
skipped, failed, deletedintegerDocuments with that outcome
cancel_requestedbooleanA cancel has been asked for
reason_codestring | nullWhy the run did not finish cleanly
error_messagestring | nullOperator-readable message
inputobjectWhat the run was started with (title, file name, size, options). Never credentials
detailobjectRun facts. A completed upload has document_id and chunks; a held sync has the change figures
created_at, started_at, completed_at, updated_atdatetimeTimestamps
duration_secondsnumber | nullcompleted_at - started_at
retryablebooleanWhether POST .../retry is accepted
supersededbooleanSingle-run reads only: a later run of the same connector exists, so a held run can no longer be approved

Statuses

StatusMeaning
queuedRecorded, waiting for a worker
runningA worker is processing it
completedEverything was applied
completed_with_errorsSome documents failed; the rest were applied
held_for_reviewA sync would change or delete more than the threshold allows. Nothing was applied. Approve it with POST /connectors/{id}/sync/approve
failedNothing was applied, or the source could not be read
cancelledCancelled before it finished; work already applied stays applied

A run left queued or running with no update for STALE_JOB_TIMEOUT_MINUTES (default 60) is marked failed with reason_code = "abandoned". It is not run again automatically.

Reason codes

reason_code appears on runs and on run items. Clients should show an unknown code using the accompanying error_message or detail.

CodeMeaning
unchangedAlready up to date; skipped
removed_at_sourceNo longer at the source, so it was deleted here
unsupported_formatThe file type cannot be read
too_largeOver a size limit
no_extractable_textNo text was found
invalid_documentThe source sent a record without the required fields
embedding_pendingIndexed for keyword search; some chunks have no vector yet
source_refusedThe source rejected the sign-in or the request
source_unreachableThe source did not answer
not_configuredA required credential or setting is missing
permissions_failedContent synced, but source sharing could not be read
large_changeHeld for review by the large-change check
all_documents_failedEvery document in a sync failed
restricted_at_sourceLeft out because the source restricts who may view it and the connector does not mirror that (Confluence)
document_limit_reachedThe plan's document limit is reached
insufficient_creditsNot enough credits for a scheduled sync
billing_unconfiguredA scheduled sync could not be priced because no rate is configured
not_authorizedThe requester may not write to the destination
input_expiredThe staged input is no longer kept
abandonedNo worker settled the run in time
internal_errorUnexpected error

File extraction adds its own codes, for example no_text_layer and encrypted_pdf.

Endpoints

GET /api/v1/ingestion/runs

Runs for the organization, newest first.

QueryTypeDescription
connector_idstringOnly this connector's syncs
collection_idstringOnly runs into this collection
kindstringupload, text, sync, reprocess or permissions
statusstringOne run status
added_by_handbooleanLeave out connector syncs
no_collectionbooleanOnly runs with no destination collection
beforedatetimecreated_at of the last run on the previous page
limitinteger1 to 100, default 25

Response:

{"runs": [{"id": "...", "kind": "sync", "status": "completed"}], "next_before": "2026-10-14T09:00:00Z"}

next_before is null on the last page. Pass it as before for the next page.

GET /api/v1/ingestion/runs/{run_id}

One run and a breakdown of its items. This is the URL returned as status_url.

{
  "run": {"id": "...", "status": "completed_with_errors", "failed": 2, "superseded": false},
  "reasons": [{"outcome": "failed", "reason_code": "no_text_layer", "count": 2}]
}

Returns 400 for a malformed id and 404 for a run in another organization.

GET /api/v1/ingestion/runs/{run_id}/items

Documents in the run that were skipped, failed or deleted, plus documents that indexed with a note (embedding_pending). Documents that indexed cleanly are counted on the run and have no item.

QueryTypeDescription
outcomestringindexed, skipped, failed or deleted
reason_codestringOne reason code
limitinteger1 to 200, default 50
offsetintegerDefault 0

Response: {"items": [...], "has_more": false}. An item has id, source_ref, title, doc_id, stage, outcome, reason_code, detail and created_at.

POST /api/v1/ingestion/runs/{run_id}/retry

Run it again as a new run. Returns 202:

{"run_id": "<new-run-id>", "status": "queued", "status_url": "/api/v1/ingestion/runs/<new-run-id>"}
  • The caller needs the Knowledge product grant and write access to the run's destination; 403 otherwise.
  • Accepted for a run that is failed, cancelled or completed_with_errors. Reprocess runs cannot be retried. Otherwise 409.
  • An upload or pasted document is retried from its staged input. The input is kept after a failure for INGESTION_FAILED_INPUT_RETENTION_HOURS (default 24). After that the response is 409 with detail.error = "input_expired"; add the document again.
  • A sync is started again. 409 when a sync for that connector is already queued or running.

POST /api/v1/ingestion/runs/{run_id}/cancel

Cancel a run that has not finished.

{"run_id": "<run-id>", "status": "cancelled", "cancel_requested": true}

A queued run is cancelled at once. A running sync returns status: "running", stops before its next document and settles as cancelled; documents it already applied stay applied. Returns 409 when the run has already finished.

GET /api/v1/ingestion/sources

Every source of knowledge in one list: each connector, and each collection's uploaded and pasted documents. Response: {"sources": [...]}.

  • A connector row is the connector object from the Connectors API with kind: "connector" and collection_name.
  • An uploads row has kind: "uploads", id (uploads:<collection-id>, or uploads:none), name, type_name, collection_id, collection_name, connection (status: "not_required"), freshness (status: "manual"), document_count, failed_documents and last_run.

GET /api/v1/ingestion/summary

What needs attention across all sources and how much of the plan is used.

{
  "documents": {"total": 412, "size_bytes": 88211456, "failed": 3, "in_progress": 0},
  "limits": {"max_documents": 1000, "max_storage_gb": 5, "max_upload_mb": 100},
  "active_runs": 1,
  "failure_reasons": [{"reason_code": "no_text_layer", "count": 2}]
}

max_documents and max_storage_gb are null when the plan sets no limit. failure_reasons covers failed items from the last 14 days. The numbers above are an example, not defaults.

Removed routes

These no longer exist: /api/v1/ingestion/jobs, /api/v1/ingestion/jobs/{job_id} and its /retry and /cancel, /api/v1/ingestion/batch-jobs, /api/v1/ingestion/stats, every /api/v1/workflows/* route and POST /api/v1/ingest/{doc_id}/graph.

On this page