Class: IngestionSession
@kortexya/reasoninglayer / IngestionSession
Class: IngestionSession
Section titled “Class: IngestionSession”Defined in: src/resources/ingestion-session.ts:490
Handle for a queued single-document ingestion — the HTTP 202 answer of
ingestDocument, ingestMarkdown or ingestRdf with sync: false.
Remarks
Section titled “Remarks”documentId is the session-tracking id of the document. The
document-registry id (the one GET /api/v1/documents lists) is
documentTermId in IngestionSessionHandle.getStats once the
document completes.
Example
Section titled “Example”const outcome = await client.ingestion.ingestMarkdown(request, { sync: false });if (outcome.kind === 'queued') { const stats = await outcome.session.waitForCompletion({ onProgress: (p) => console.log(p.documents[0]?.currentStepLabel), }); console.log(stats.documents[0]?.documentTermId);}Extends
Section titled “Extends”Properties
Section titled “Properties”documentId
Section titled “documentId”
readonlydocumentId:string
Defined in: src/resources/ingestion-session.ts:492
Session-tracking id of the queued document (UUID).
sessionId
Section titled “sessionId”
readonlysessionId:string
Defined in: src/resources/ingestion-session.ts:201
The session ID (UUID).
Inherited from
Section titled “Inherited from”IngestionSessionHandle.sessionId
status
Section titled “status”
readonlystatus:string
Defined in: src/resources/ingestion-session.ts:204
The status at enqueue time. The engine always sends "pending".
Inherited from
Section titled “Inherited from”statusUrl
Section titled “statusUrl”
readonlystatusUrl:string
Defined in: src/resources/ingestion-session.ts:207
Path of the session resource (/api/v1/ingest/sessions/<sessionId>).
Inherited from
Section titled “Inherited from”IngestionSessionHandle.statusUrl
Methods
Section titled “Methods”getDocumentStats()
Section titled “getDocumentStats()”getDocumentStats(
documentId,requestOptions?):Promise<DocumentStatsDto|null>
Defined in: src/resources/ingestion-session.ts:315
Get the stats of one document of the session.
Parameters
Section titled “Parameters”documentId
Section titled “documentId”string
The document’s session-tracking id (the documentId
the 202 answer, or DocumentStatsDto.documentId, names).
requestOptions?
Section titled “requestOptions?”Per-call request options.
Returns
Section titled “Returns”Promise<DocumentStatsDto | null>
The document’s stats once it completed, or null while it is
still pending or in progress (HTTP 204).
Throws
Section titled “Throws”404 if the session or the document does not
exist, the document is an RDF import (its receipt is on
IngestionSessionHandle.getSession), or it completed without recording stats.
Throws
Section titled “Throws”409 if the document failed or was
cancelled; the reason is documents[].error on IngestionSessionHandle.getSession.
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}/documents/{document_id}/stats.
The engine publishes DocumentStatsDto as the 200 body; a 204 (still
pending or in progress) reads as null.
DocumentStatsDto.alreadyIngested tells a duplicate upload from a
fresh ingestion.
Example
Section titled “Example”const stats = await session.getDocumentStats(documentId);if (stats?.alreadyIngested) console.log(`already in the library as ${stats.documentTermId}`);Inherited from
Section titled “Inherited from”IngestionSessionHandle.getDocumentStats
getProgress()
Section titled “getProgress()”getProgress(
requestOptions?):Promise<SessionProgressResponse>
Defined in: src/resources/ingestion-session.ts:263
Get live pipeline progress for all documents in the session.
Parameters
Section titled “Parameters”requestOptions?
Section titled “requestOptions?”Returns
Section titled “Returns”Promise<SessionProgressResponse>
Progress snapshots for each document being processed.
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}/progress.
Returns real-time counters, current pipeline step, and step log.
Inherited from
Section titled “Inherited from”IngestionSessionHandle.getProgress
getSession()
Section titled “getSession()”getSession(
requestOptions?):Promise<IngestionSessionDetailResponse>
Defined in: src/resources/ingestion-session.ts:246
Get the current session details: status, document counts, and every document with how its ingestion ended.
Parameters
Section titled “Parameters”requestOptions?
Section titled “requestOptions?”Per-call request options.
Returns
Section titled “Returns”Promise<IngestionSessionDetailResponse>
The session, with documents[]: each document’s status, its
failure reason (error) and, once complete, its receipt.
Throws
Section titled “Throws”404 if the session does not exist.
Throws
Section titled “Throws”If the request fails.
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}. A receipt is tagged by
kind: markdown carries the document stats, rdf the RDF import counts
(an RDF document has no other stats route).
Example
Section titled “Example”const session = await handle.getSession();for (const doc of session.documents) { if (doc.receipt?.kind === 'rdf') console.log(`${doc.receipt.sortsCreated} sorts`);}Inherited from
Section titled “Inherited from”IngestionSessionHandle.getSession
getStats()
Section titled “getStats()”getStats(
requestOptions?):Promise<SessionStatsResponse>
Defined in: src/resources/ingestion-session.ts:280
Get stats for all completed documents in the session.
Parameters
Section titled “Parameters”requestOptions?
Section titled “requestOptions?”Returns
Section titled “Returns”Promise<SessionStatsResponse>
Per-document stats (term IDs, sort names, token usage, etc.).
Remarks
Section titled “Remarks”Maps to GET /api/v1/ingest/sessions/{session_id}/stats.
May be empty if no documents have completed yet.
Inherited from
Section titled “Inherited from”IngestionSessionHandle.getStats
waitForCompletion()
Section titled “waitForCompletion()”waitForCompletion(
options?):Promise<SessionStatsResponse>
Defined in: src/resources/ingestion-session.ts:351
Poll the session until it completes or fails, then return final stats.
Parameters
Section titled “Parameters”options?
Section titled “options?”Polling configuration (interval, timeout, progress callback, abort signal).
Returns
Section titled “Returns”Promise<SessionStatsResponse>
Final session stats once all documents are complete. These are
the markdown pipeline’s stats: an RDF document has none, so for an
ingestRdf session use IngestionSessionHandle.waitForSession,
whose documents carry the RDF receipt.
Throws
Section titled “Throws”IngestionFailedError If the session status becomes "failed".
Throws
Section titled “Throws”TimeoutError If timeoutMs is exceeded.
Throws
Section titled “Throws”ReasoningLayerError If the abort signal is triggered.
Example
Section titled “Example”const stats = await session.waitForCompletion({ pollIntervalMs: 2000, timeoutMs: 300_000, onProgress: (p) => { const doc = p.documents[0]; if (doc) console.log(`${doc.currentStepLabel} — chunk ${doc.chunksProcessed}/${doc.totalChunks}`); },});console.log(`Created ${stats.documents[0]?.termIds.length} terms`);Remarks
Section titled “Remarks”Polls getSession() to check status, and calls onProgress with live
progress data between checks. Terminal states are "complete" and "failed".
Inherited from
Section titled “Inherited from”IngestionSessionHandle.waitForCompletion
waitForSession()
Section titled “waitForSession()”waitForSession(
options?):Promise<IngestionSessionDetailResponse>
Defined in: src/resources/ingestion-session.ts:382
Poll the session until it completes or fails, then return the session with every document’s receipt.
Parameters
Section titled “Parameters”options?
Section titled “options?”Polling configuration (interval, timeout, progress callback, abort signal).
Returns
Section titled “Returns”Promise<IngestionSessionDetailResponse>
The completed session. Each document carries its receipt:
kind: 'markdown' with the document stats, or kind: 'rdf' with the
RDF import counts.
Throws
Section titled “Throws”IngestionFailedError If the session status becomes
"failed"; its session.documents[].error names each reason.
Throws
Section titled “Throws”TimeoutError If timeoutMs is exceeded.
Throws
Section titled “Throws”ReasoningLayerError If the abort signal is triggered.
Remarks
Section titled “Remarks”Polls getSession() the same way IngestionSessionHandle.waitForCompletion
does, and returns its last answer instead of fetching the markdown stats.
Use it for an ingestRdf session queued with sync: false.
Example
Section titled “Example”const handle = await client.ingestion.ingestRdf(request, { sync: false });const session = await handle.waitForSession();const receipt = session.documents[0]?.receipt;if (receipt?.kind === 'rdf') console.log(`${receipt.termsCreated} terms`);