Appearance

Jobs ​

Monitor and manage background ingestion jobs (parsing, chunking, embedding). See the Job status values in the overview.

List queued and in-progress ingestion jobs​

GET
/v1/jobs

Returns ingestion jobs (parse / chunk / embed) registered for the caller, plus current queue depth. By default only non-terminal states (PENDING, STARTED, PROGRESS, RETRY) are included; set include_finished=true to also list SUCCESS / FAILURE.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Query Parameters

include_finished

Include SUCCESS, FAILURE, and REVOKED jobs.

Type
boolean
Default
false

Responses​

Successful Response

application/json
JSON
{
  
"broker": {
  
  
"active_count": 0,
  
  
"pending_count": 0,
  
  
"reserved_count": 0,
  
  
"scheduled_count": 0,
  
  
"workers_responding": 0
  
},
  
"jobs": [
  
  
{
  
  
  
"job_id": "string",
  
  
  
"operation": "string",
  
  
  
"progress": {
  
  
  
  
"already_crawled": true,
  
  
  
  
"already_crawled_count": 0,
  
  
  
  
"crawled_docs": [
  
  
  
  
  
{
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
}
  
  
  
  
],
  
  
  
  
"current": 0,
  
  
  
  
"document_id": "string",
  
  
  
  
"document_name": "string",
  
  
  
  
"failed_urls": [
  
  
  
  
  
{
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
}
  
  
  
  
],
  
  
  
  
"limit_hit": true,
  
  
  
  
"message": "string",
  
  
  
  
"stage": "string",
  
  
  
  
"total": 0,
  
  
  
  
"uncrawled_frontier": 0
  
  
  
},
  
  
  
"state": "string"
  
  
}
  
]
}

Samples​

Query the job status audit log​

GET
/v1/jobs/audit

Returns paginated, filtered entries from the job status audit log, scoped to the authenticated user. Supports filtering by job_id, status, operation, and created_at range.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Query Parameters

job_id

Filter by job id.

status

Filter by status (PENDING, STARTED, PROGRESS, SUCCESS, FAILURE, RETRY, REVOKED).

operation

Filter by operation (parsing, chunking, embedding, web_crawl, anchor_embedding, draft_eval, draft_version_embedding, echo_postprocess, chat_title_generation).

created_from

Include entries created at or after this timestamp (ISO 8601).

created_to

Include entries created at or before this timestamp (ISO 8601).

limit

Max entries to return.

Type
integer
Default
50
Maximum
200
Minimum
1
offset

Number of entries to skip.

Type
integer
Default
0
Minimum
0

Responses​

Successful Response

application/json
JSON
{
  
"items": [
  
  
{
  
  
  
"created_at": "string",
  
  
  
"elapsed_seconds": 0,
  
  
  
"error": "string",
  
  
  
"job_id": "string",
  
  
  
"operation": "string",
  
  
  
"status": "string",
  
  
  
"user_id": "string"
  
  
}
  
],
  
"limit": 0,
  
"offset": 0,
  
"total": 0
}

Samples​

SSE stream of job status updates​

GET
/v1/jobs/stream

Server-Sent Events stream that pushes job completion/failure events in real time. Replaces polling.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Responses​

Successful Response

application/json
JSON
[
]

Samples​

Check status of a background job​

GET
/v1/jobs/{job_id}

Poll the state of a background job id. Requires authentication; the job id acts as an opaque capability.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

job_id*
Type
string
Required

Query Parameters

cursor

Last progress-event id; returns events after it.

Responses​

Successful Response

application/json
JSON
{
  
"cursor": "string",
  
"elapsed_seconds": 0,
  
"error": "string",
  
"events": [
  
  
{
  
  
  
"additionalProperties": "string"
  
  
}
  
],
  
"job_id": "string",
  
"operation": "string",
  
"payload": {
  
  
"additionalProperties": "string"
  
},
  
"progress": {
  
  
"already_crawled": true,
  
  
"already_crawled_count": 0,
  
  
"crawled_docs": [
  
  
  
{
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
],
  
  
"current": 0,
  
  
"document_id": "string",
  
  
"document_name": "string",
  
  
"failed_urls": [
  
  
  
{
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
],
  
  
"limit_hit": true,
  
  
"message": "string",
  
  
"stage": "string",
  
  
"total": 0,
  
  
"uncrawled_frontier": 0
  
},
  
"result": 0,
  
"state": "string"
}

Samples​

Cancel a background job by id​

POST
/v1/jobs/{job_id}/revoke

Requests cancellation of this job. terminate=true (default) also interrupts the job if it is already running; terminate=false only prevents it from starting. The job id is the opaque capability returned when ingestion was queued.

Authorizations​

HTTPBearer
Type
HTTP (bearer)

Parameters​

Path Parameters

job_id*
Type
string
Required

Query Parameters

terminate

If true, also interrupt the job if it is already running; if false, only prevent it from starting.

Type
boolean
Default
true

Responses​

Successful Response

application/json
JSON
{
  
"job_id": "string",
  
"message": "Cancellation requested. The job stops at the next safe point; already-completed work is not rolled back.",
  
"terminate": true
}

Samples​