inndx
GitHub

Runs

Create, inspect, and control the lifecycle of crawl job runs.

A run is a single execution of a crawl job. Each run tracks its own status, timing, and the resolved configuration it executed with.

These endpoints share the pagination and error conventions.

List runs

GET/v1/runs

Returns a page of runs across all jobs, most recent first.

Query parametersin: query
page
string

Pagination cursor. See pagination.

per_page
numberdefault: 10

Maximum number of runs to return.

min: 1max: 100
job_ids
string[]

Return only runs belonging to these jobs.

format: uuid
include_ids
string[]

Return only runs with these IDs.

format: uuid
exclude_ids
string[]

Omit runs with these IDs.

format: uuid
statuses
string[]

Return only runs in these statuses.

pending
Created but not yet started.
running
Currently executing.
paused
Temporarily halted and resumable.
finished
Completed or stopped.
stop_reasons
string[]

Return only runs that stopped for these reasons.

max_depth
Reached the configured crawl depth limit.
max_urls
Reached the configured URL limit.
max_empty_evaluations
Reached the limit of consecutive empty evaluations.
max_age
Reached the configured maximum run age.
manual
Stopped by request.
empty_seed
No seed URLs were available to crawl.
unknown
Stopped for an unrecorded reason.
created_before
string

Return only runs created before this timestamp.

format: date-time
created_after
string

Return only runs created after this timestamp.

format: date-time
labels
object

Return only runs whose labels match every supplied key and value.

Responses

curl 'http://localhost:8022/v1/runs?per_page=20&statuses=running' \
  -H 'X-Tenant-Id: acme'

List runs for a job

GET/v1/jobs/{job_id}/runs

Returns a page of runs belonging to a single job, most recent first. The {job_id} path segment is the job's UUID.

Query parametersin: query
page
string

Pagination cursor. See pagination.

per_page
numberdefault: 10

Maximum number of runs to return.

min: 1max: 100
include_ids
string[]

Return only runs with these IDs.

format: uuid
exclude_ids
string[]

Omit runs with these IDs.

format: uuid
statuses
string[]

Return only runs in these statuses.

pending
Created but not yet started.
running
Currently executing.
paused
Temporarily halted and resumable.
finished
Completed or stopped.
stop_reasons
string[]

Return only runs that stopped for these reasons.

max_depth
Reached the configured crawl depth limit.
max_urls
Reached the configured URL limit.
max_empty_evaluations
Reached the limit of consecutive empty evaluations.
max_age
Reached the configured maximum run age.
manual
Stopped by request.
empty_seed
No seed URLs were available to crawl.
unknown
Stopped for an unrecorded reason.
created_before
string

Return only runs created before this timestamp.

format: date-time
created_after
string

Return only runs created after this timestamp.

format: date-time
labels
object

Return only runs whose labels match every supplied key and value.

Responses

curl 'http://localhost:8022/v1/jobs/3f1a…/runs?per_page=20' \
  -H 'X-Tenant-Id: acme'

Create a run

POST/v1/jobs/{job_id}/runs

Creates a run for a job. The {job_id} path segment is the job's UUID.

Request bodyin: body
id
string

The ID to assign. Generated when omitted.

format: uuid
Responses

curl -X POST 'http://localhost:8022/v1/jobs/3f1a…/runs' \
  -H 'X-Tenant-Id: acme' \
  -H 'Content-Type: application/json' \
  -d '{}'

Get a run

GET/v1/runs/{run_id}

Returns a single run by ID. The {run_id} path segment is the run's UUID.

Responses

curl 'http://localhost:8022/v1/runs/9c2b…' \
  -H 'X-Tenant-Id: acme'

Delete a run

DELETE/v1/runs/{run_id}

Deletes a run. The {run_id} path segment is the run's UUID.

Responses

curl -X DELETE 'http://localhost:8022/v1/runs/9c2b…' \
  -H 'X-Tenant-Id: acme'

Pause a run

PUT/v1/runs/{run_id}/pause

Pauses a running run. The {run_id} path segment is the run's UUID.

Responses

curl -X PUT 'http://localhost:8022/v1/runs/9c2b…/pause' \
  -H 'X-Tenant-Id: acme'

Resume a run

PUT/v1/runs/{run_id}/resume

Resumes a paused run. The {run_id} path segment is the run's UUID.

Responses

curl -X PUT 'http://localhost:8022/v1/runs/9c2b…/resume' \
  -H 'X-Tenant-Id: acme'

Stop a run

PUT/v1/runs/{run_id}/stop

Stops a run, recording a manual stop reason. The {run_id} path segment is the run's UUID.

Responses

curl -X PUT 'http://localhost:8022/v1/runs/9c2b…/stop' \
  -H 'X-Tenant-Id: acme'

Search docs

Search the Self-host documentation