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
| Property | Type | Description |
|---|---|---|
id | string | Run id |
org_id | string | Organization |
kind | string | upload, text, sync, reprocess or permissions |
trigger | string | manual, schedule, approval, retry or api |
status | string | See Statuses |
connector_id | string | null | Set for syncs |
collection_id | string | null | Destination collection |
requested_by | string | null | User who started it |
retry_of | string | null | The run this one retries |
title | string | null | Document title or connector name |
stage | string | null | discover, fetch, parse, chunk, embed, index or permissions |
discovered, fetched, parsed, chunked, embedded, indexed | integer | Documents that reached each stage |
skipped, failed, deleted | integer | Documents with that outcome |
cancel_requested | boolean | A cancel has been asked for |
reason_code | string | null | Why the run did not finish cleanly |
error_message | string | null | Operator-readable message |
input | object | What the run was started with (title, file name, size, options). Never credentials |
detail | object | Run facts. A completed upload has document_id and chunks; a held sync has the change figures |
created_at, started_at, completed_at, updated_at | datetime | Timestamps |
duration_seconds | number | null | completed_at - started_at |
retryable | boolean | Whether POST .../retry is accepted |
superseded | boolean | Single-run reads only: a later run of the same connector exists, so a held run can no longer be approved |
Statuses
| Status | Meaning |
|---|---|
queued | Recorded, waiting for a worker |
running | A worker is processing it |
completed | Everything was applied |
completed_with_errors | Some documents failed; the rest were applied |
held_for_review | A sync would change or delete more than the threshold allows. Nothing was applied. Approve it with POST /connectors/{id}/sync/approve |
failed | Nothing was applied, or the source could not be read |
cancelled | Cancelled 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.
| Code | Meaning |
|---|---|
unchanged | Already up to date; skipped |
removed_at_source | No longer at the source, so it was deleted here |
unsupported_format | The file type cannot be read |
too_large | Over a size limit |
no_extractable_text | No text was found |
invalid_document | The source sent a record without the required fields |
embedding_pending | Indexed for keyword search; some chunks have no vector yet |
source_refused | The source rejected the sign-in or the request |
source_unreachable | The source did not answer |
not_configured | A required credential or setting is missing |
permissions_failed | Content synced, but source sharing could not be read |
large_change | Held for review by the large-change check |
all_documents_failed | Every document in a sync failed |
restricted_at_source | Left out because the source restricts who may view it and the connector does not mirror that (Confluence) |
document_limit_reached | The plan's document limit is reached |
insufficient_credits | Not enough credits for a scheduled sync |
billing_unconfigured | A scheduled sync could not be priced because no rate is configured |
not_authorized | The requester may not write to the destination |
input_expired | The staged input is no longer kept |
abandoned | No worker settled the run in time |
internal_error | Unexpected 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.
| Query | Type | Description |
|---|---|---|
connector_id | string | Only this connector's syncs |
collection_id | string | Only runs into this collection |
kind | string | upload, text, sync, reprocess or permissions |
status | string | One run status |
added_by_hand | boolean | Leave out connector syncs |
no_collection | boolean | Only runs with no destination collection |
before | datetime | created_at of the last run on the previous page |
limit | integer | 1 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.
| Query | Type | Description |
|---|---|---|
outcome | string | indexed, skipped, failed or deleted |
reason_code | string | One reason code |
limit | integer | 1 to 200, default 50 |
offset | integer | Default 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;
403otherwise. - Accepted for a run that is
failed,cancelledorcompleted_with_errors. Reprocess runs cannot be retried. Otherwise409. - 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 is409withdetail.error = "input_expired"; add the document again. - A sync is started again.
409when 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"andcollection_name. - An uploads row has
kind: "uploads",id(uploads:<collection-id>, oruploads:none),name,type_name,collection_id,collection_name,connection(status: "not_required"),freshness(status: "manual"),document_count,failed_documentsandlast_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.