Skip to main content
POST
/
api
/
jobs
/
{job_id}
/
progress
Report Job Progress
curl --request POST \
  --url https://api.merchantops.ai/api/jobs/{job_id}/progress \
  --header 'Content-Type: application/json' \
  --data '
{
  "error": {
    "entity_key": "<string>",
    "error_type": "<string>",
    "message": "<string>",
    "details": {},
    "entity_type": "job",
    "step": "<string>"
  },
  "mark_completed": false,
  "mark_failed": "<string>",
  "mark_started": false,
  "message": "<string>",
  "metadata_patch": {},
  "processed_items": 1,
  "stage": "<string>",
  "total_items": 1,
  "warning": {
    "entity_key": "<string>",
    "error_type": "<string>",
    "message": "<string>",
    "details": {},
    "entity_type": "job",
    "step": "<string>"
  }
}
'
{
  "failed_items": 123,
  "job_id": "<string>",
  "job_type": "<string>",
  "processed_items": 123,
  "progress_percentage": 123,
  "status": "<string>",
  "success_rate": 123,
  "total_items": 123,
  "completed_at": "<string>",
  "created_at": "<string>",
  "duration_seconds": 123,
  "error_message": "<string>",
  "errors": [
    {
      "entity_key": "<string>",
      "entity_type": "<string>",
      "error_type": "<string>",
      "message": "<string>",
      "timestamp": "<string>",
      "details": {},
      "step": "<string>"
    }
  ],
  "metadata": {},
  "started_at": "<string>",
  "triggered_by": "<string>",
  "warned_items": 0,
  "warnings": [
    {
      "entity_key": "<string>",
      "entity_type": "<string>",
      "error_type": "<string>",
      "message": "<string>",
      "timestamp": "<string>",
      "details": {},
      "step": "<string>"
    }
  ]
}

Headers

​
authorization
string | null
​
X-Organization-ID
string | null

Path Parameters

​
job_id
string
required

Cookies

​
stytch_session
string | null

Body

application/json

Worker progress update — single endpoint for the lifecycle of a Job that the worker itself created.

Designed for inbound-feed workers (e.g. rrs-oracle-import-worker) that don't have a database connection — they create the Job via POST /api/jobs/ and then call this endpoint at each phase transition. All fields are optional; only provided fields take effect.

​
error
JobProgressErrorBody · object

Append an error to the Job's errors[] array

​
mark_completed
boolean
default:false

If true, mark the Job complete (auto-derives COMPLETED / COMPLETED_WITH_WARNINGS / PARTIAL_SUCCESS)

​
mark_failed
string | null

If set, mark the Job failed with this message as error_message

​
mark_started
boolean
default:false

If true, transition status to in_progress

​
message
string | null

Optional log line stamped on metadata.last_message

​
metadata_patch
Metadata Patch · object

Arbitrary metadata fields to merge under metadata.* — e.g. {'import_job_id': 'enrichment-...'} to cross-link the downstream job.

​
processed_items
integer | null

Set processed_items directly. Useful for inbound-feed workers that dispatch a batch downstream (e.g. via /import-json-async) and need the parent Job to reflect progress without a per-item NATS bus.

Required range: x >= 0
​
stage
string | null

Sets metadata.stage (e.g. 'downloading', 'transforming', 'uploading', 'dispatched').

​
total_items
integer | null

Update total_items (e.g. set after the worker counts the rows in a downloaded file).

Required range: x >= 0
​
warning
JobProgressErrorBody · object

Append a warning to the Job's warnings[] array

Response

Successful Response

Response model for a single Job.

​
failed_items
integer
required

Items that failed

​
job_id
string
required

Unique job identifier

​
job_type
string
required

Type of job (enrichment or crawl)

​
processed_items
integer
required

Items successfully processed

​
progress_percentage
number
required

Progress percentage (0-100)

​
status
string
required

Current job status

​
success_rate
number
required

Success rate percentage (0-100)

​
total_items
integer
required

Total items to process

​
completed_at
string | null

Job completion timestamp

​
created_at
string | null

Job creation timestamp

​
duration_seconds
number | null

Job duration in seconds

​
error_message
string | null

DEPRECATED: Use 'errors' array. Legacy error message

​
errors
JobErrorResponse · object[]

Array of errors that occurred

​
metadata
Metadata · object

Job metadata

​
started_at
string | null

Job start timestamp

​
triggered_by
string | null

User who triggered the job

​
warned_items
integer
default:0

Items processed with warnings (e.g., expected target gaps)

​
warnings
JobErrorResponse · object[]

Array of non-blocking warnings (same shape as errors)