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>"
  }
}
'

import requests

url = "https://api.merchantops.ai/api/jobs/{job_id}/progress"

payload = {
    "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>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
    }
  })
};

fetch('https://api.merchantops.ai/api/jobs/{job_id}/progress', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.merchantops.ai/api/jobs/{job_id}/progress",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.merchantops.ai/api/jobs/{job_id}/progress"

	payload := strings.NewReader("{\n  \"error\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  },\n  \"mark_completed\": false,\n  \"mark_failed\": \"<string>\",\n  \"mark_started\": false,\n  \"message\": \"<string>\",\n  \"metadata_patch\": {},\n  \"processed_items\": 1,\n  \"stage\": \"<string>\",\n  \"total_items\": 1,\n  \"warning\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.merchantops.ai/api/jobs/{job_id}/progress")
  .header("Content-Type", "application/json")
  .body("{\n  \"error\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  },\n  \"mark_completed\": false,\n  \"mark_failed\": \"<string>\",\n  \"mark_started\": false,\n  \"message\": \"<string>\",\n  \"metadata_patch\": {},\n  \"processed_items\": 1,\n  \"stage\": \"<string>\",\n  \"total_items\": 1,\n  \"warning\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.merchantops.ai/api/jobs/{job_id}/progress")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"error\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  },\n  \"mark_completed\": false,\n  \"mark_failed\": \"<string>\",\n  \"mark_started\": false,\n  \"message\": \"<string>\",\n  \"metadata_patch\": {},\n  \"processed_items\": 1,\n  \"stage\": \"<string>\",\n  \"total_items\": 1,\n  \"warning\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "failed_items": 123,
  "job_id": "<string>",
  "job_type": "<string>",
  "processed_items": 123,
  "progress_percentage": 123,
  "status": "<string>",
  "success_rate": 123,
  "total_items": 123,
  "archived_at": "<string>",
  "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": {},
  "needs_review_items": 0,
  "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>"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

Jobs

Report Job Progress

Worker progress update for a Job the caller created.

Single endpoint covering the lifecycle hooks an inbound-feed worker needs: stage transitions, total_items updates, metadata cross-links (e.g. import_job_id), error/warning appends, and mark-started / mark-completed / mark-failed transitions. Designed so customer-side workers don’t need a database connection — they call this with their ServerApiKey authentication.

Authorization: Requires job:create permission (the same permission needed to create the Job in the first place — the creator owns follow-up updates). Multi-tenancy is enforced: the request 404s if the Job’s organization_id doesn’t match the caller’s.

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>"
  }
}
'

import requests

url = "https://api.merchantops.ai/api/jobs/{job_id}/progress"

payload = {
    "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>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
    }
  })
};

fetch('https://api.merchantops.ai/api/jobs/{job_id}/progress', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.merchantops.ai/api/jobs/{job_id}/progress",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.merchantops.ai/api/jobs/{job_id}/progress"

	payload := strings.NewReader("{\n  \"error\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  },\n  \"mark_completed\": false,\n  \"mark_failed\": \"<string>\",\n  \"mark_started\": false,\n  \"message\": \"<string>\",\n  \"metadata_patch\": {},\n  \"processed_items\": 1,\n  \"stage\": \"<string>\",\n  \"total_items\": 1,\n  \"warning\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.merchantops.ai/api/jobs/{job_id}/progress")
  .header("Content-Type", "application/json")
  .body("{\n  \"error\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  },\n  \"mark_completed\": false,\n  \"mark_failed\": \"<string>\",\n  \"mark_started\": false,\n  \"message\": \"<string>\",\n  \"metadata_patch\": {},\n  \"processed_items\": 1,\n  \"stage\": \"<string>\",\n  \"total_items\": 1,\n  \"warning\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.merchantops.ai/api/jobs/{job_id}/progress")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"error\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  },\n  \"mark_completed\": false,\n  \"mark_failed\": \"<string>\",\n  \"mark_started\": false,\n  \"message\": \"<string>\",\n  \"metadata_patch\": {},\n  \"processed_items\": 1,\n  \"stage\": \"<string>\",\n  \"total_items\": 1,\n  \"warning\": {\n    \"entity_key\": \"<string>\",\n    \"error_type\": \"<string>\",\n    \"message\": \"<string>\",\n    \"details\": {},\n    \"entity_type\": \"job\",\n    \"step\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "failed_items": 123,
  "job_id": "<string>",
  "job_type": "<string>",
  "processed_items": 123,
  "progress_percentage": 123,
  "status": "<string>",
  "success_rate": 123,
  "total_items": 123,
  "archived_at": "<string>",
  "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": {},
  "needs_review_items": 0,
  "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>"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

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 | null

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

Show child attributes

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 | null

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 | null

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

Show child attributes

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

archived_at

string | null

When the job was archived (ISO 8601; null = active)

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

Show child attributes

metadata

Metadata · object | null

Job metadata

needs_review_items

integer

default:0

Items escalated to the Agent Inbox awaiting human review

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)

Show child attributes

Brands

Catalog

Jobs

Product Lakehouse

MAP Pricing

Pricing

Product Type Categories

Product Types

Products

Variants

Property Definitions

Report Job Progress

Headers

Path Parameters

Cookies

Body

Response