Skip to main content
Talk to salesStart

List bulk jobs

List native executor jobs for domains that own bulk jobs and inspect executor references when a Research Table operation run links one.

GET/api/bulk-jobs
Scope jobs:readUpdated September 27, 2026

This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.

Both endpoints accept either an authenticated user session or a developer key with jobs:read. Results are filtered by the caller's user and organization plus the Runtime v2 dispatch-model/runtime-authority pair; reads also admit the named legacy sequence-managed queue authority. List returns an empty page when no jobs match; get returns 404 for an absent or out-of-scope job. Reads do not start, cancel, or charge for work.

When to use this endpoint

  • Inspect a native executor job_id when a linked operation run includes one.
  • Show latest native jobs for a table/column when diagnosing executor state.

Research Table column runs are recovered from operationRunId via GET /api/operation-runs. Use this endpoint only for native executor diagnostics or domains whose canonical lifecycle is a bulk job. The list is newest-first and capped by limit; it has no offset/cursor parameter.

active_within_seconds is applied only if the comma-separated status filter includes one of the active statuses coalescing, queued, waiting, waiting_for_workers, pending, distributing, processing, or running. Status values are trimmed and lowercased. This is the filter's active set, not a closed list of every status the job serializer can return; other statuses do not receive the recent-activity cutoff.

The examples are abbreviated. Each job is produced by the shared executor serializer, which may include operation-run aliases, derived row counters/progress, dispatch/worker timestamps, billing fields, and bounded error details when present.

Native bulk-job inspection flow:

  1. Call GET /api/bulk-jobs?table_id=...&column_id=...&limit=1
  2. Read jobs[0].job_id
  3. Poll GET /api/bulk-jobs/{job_id} until terminal status

Query parameters

  • table_id · optional

    string

    Filter by table ID.

  • column_id · optional

    string

    Filter by column ID.

  • status · optional

    string

    Single status or comma-separated statuses.

  • provider · optional

    string

    Filter by provider.

  • active_within_seconds · optional

    integer

    60–604800 seconds. Applies a recent-activity cutoff only when status includes an active status. With no status filter or only terminal statuses, no cutoff is applied.

  • limit · optional

    integer

    1-100. Default 20.

Errors

StatusMeaning
401Invalid API key or missing auth.
403Missing jobs:read scope.
422Invalid query parameter type or active_within_seconds/limit bound.

Docs