Monitor Jobs

This guide shows you how to monitor asynchronous jobs in your Marqo ecommerce search index. Learn about job statuses, how to retrieve job information, and best practices for tracking document operations.

Prerequisites

A Marqo Cloud account
Your Marqo API key
An existing ecommerce index

Understanding Asynchronous Jobs

When you perform document operations (adding, updating, or deleting products), these operations are asynchronous. This means:

Immediate Response: Your request is accepted immediately and you receive a job ID
Background Processing: The actual operation happens in the background
Status Tracking: You can monitor progress using the job ID
Error Handling: Success or failure details are available once processing completes

Job Operations

Get All Jobs

Retrieve recent jobs for your index (by default, the last 24 hours):

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs \
-H "Authorization: Bearer {api_key}"

Get Specific Job

Retrieve details for a specific job using its job ID:

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs/{job_id} \
-H "Authorization: Bearer {api_key}"

Filter Jobs by Status

Get Pending Jobs

Jobs that are queued but not yet started:

curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs?status=PENDING" \
-H "Authorization: Bearer {api_key}"

Get In-Progress Jobs

Jobs that are currently running:

curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs?status=IN_PROGRESS" \
-H "Authorization: Bearer {api_key}"

Get Failed Jobs

Jobs that encountered errors:

curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs?status=FAILED" \
-H "Authorization: Bearer {api_key}"

Filter by Time Range

You can combine filters with a time window to focus on a specific period (useful for alerting and incident reviews). The /jobs endpoint accepts the following query parameters:

Parameter	Type	Description
`status`	String (optional)	Filter to `PENDING`, `IN_PROGRESS`, `COMPLETED`, `FAILED`, `CONFLICT`, or `CANCELLED`. If omitted, all statuses are returned.
`timeFrom`	ISO 8601 string (optional)	Start timestamp for the results window (e.g. `2025-11-06T01:10:12+00:00`). If omitted, defaults to 24 hours ago. Must be within the last 30 days.
`timeTo`	ISO 8601 string (optional)	End timestamp for the results window. If omitted, defaults to "now". Must not be in the future.
`limit`	Integer (optional)	Maximum number of jobs to return. Default `10`, maximum `1000`.

Example: retrieve up to 100 failed jobs from a one-week period (use timestamps within the last 30 days):

curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs?status=FAILED&timeFrom={iso_time_from}&timeTo={iso_time_to}&limit=100" \
-H "Authorization: Bearer {api_key}"

Tips

Encode timestamps if your tooling requires it (: becomes %3A, + becomes %2B).
You can omit status to retrieve all jobs within a time range.
Combine timeFrom/timeTo with limit to page through long-running histories.

Note: Replace {index_name} with your actual index name, {api_key} with your API key, and {job_id} with the specific job ID you want to check.

Job Statuses

Jobs can have the following statuses:

Status	Description
`PENDING`	Job is queued and waiting to be processed
`IN_PROGRESS`	Job is currently being processed
`COMPLETED`	Job finished processing successfully
`FAILED`	Job completed with errors (see `failedItemsDetails` / `errorSummary`)
`CONFLICT`	Job completed but some documents were skipped due to version conflicts (see `conflict*` fields)
`CANCELLED`	Job was cancelled before completion

Response Fields

List Jobs Response

Field	Type	Description
`jobs`	Array	List of job objects (most recent first)
`total`	Integer	Total number of jobs in the selected time window (may exceed the number returned under `jobs`)
`totalDocs`	Integer	Total number of documents currently in the index
`hasActiveJob`	Boolean	Whether there is any `PENDING` or `IN_PROGRESS` job in the returned `jobs`
`jobsByStatus`	Object	Count of jobs by status across the returned `jobs`
`docsByStatus`	Object	Aggregated document outcomes across the returned `jobs`
`timeFrom`	String	Start timestamp of the selected time window
`timeTo`	String	End timestamp of the selected time window

Job Object Fields

Field	Type	Description
`jobId`	String	Unique identifier for the job
`jobType`	String	Type of operation (e.g. `BULK`, `WEBHOOK`, `COLLECTION_PATCH`)
`jobStatus`	String	Current status of the job
`platformData`	Object	Platform-specific job metadata (contents depend on `jobType`)
`totalItems`	Integer	Total number of items in the job
`processedItems`	Integer	Number of items processed successfully
`failedItems`	Integer	Number of items that failed processing
`skippedItems`	Integer	Number of items skipped (non-error)
`conflictItems`	Integer	Number of items skipped due to version conflicts
`errorMessage`	String/null	General error message if the job failed
`failedItemsDetails`	Object	Map of error types to lists of failed item IDs
`errorSummary`	Object	Count of items per error type
`skippedItemsDetails`	Object	Map of skip reasons to lists of skipped item IDs
`skippedSummary`	Object	Count of items per skip reason
`conflictDetails`	Object	Map of conflict reasons to conflict objects (e.g. conflicting `jobId`s)
`conflictSummary`	Object	Count of items per conflict reason
`createdAt`	String	ISO timestamp when job was created
`startedAt`	String/null	ISO timestamp when job started processing
`completedAt`	String/null	ISO timestamp when job completed
`progressPercentage`	Float	Completion percentage (0.0 to 100.0)
`estimatedTimeMinutes`	Integer/null	Estimated time for job completion

Response Examples

All Jobs Response

{
  "jobs": [
    {
      "jobId": "4eb23b8c-8d50-4a39-9bb1-490d8e6df521",
      "jobType": "BULK",
      "jobStatus": "COMPLETED",
      "platformData": {},
      "totalItems": 3,
      "processedItems": 3,
      "failedItems": 0,
      "skippedItems": 0,
      "conflictItems": 0,
      "errorMessage": null,
      "failedItemsDetails": {},
      "errorSummary": {},
      "skippedItemsDetails": {},
      "skippedSummary": {},
      "conflictDetails": {},
      "conflictSummary": {},
      "createdAt": "2025-08-12T14:50:22.272035+00:00",
      "startedAt": "2025-08-12T14:50:24.936806+00:00",
      "completedAt": "2025-08-12T14:50:35.980820+00:00",
      "progressPercentage": 100.0,
      "estimatedTimeMinutes": 1
    }
  ],
  "total": 1,
  "totalDocs": 1234,
  "hasActiveJob": false,
  "jobsByStatus": {
    "COMPLETED": 1
  },
  "docsByStatus": {
    "PROCESSED": 3,
    "FAILED": 0,
    "SKIPPED": 0,
    "PENDING": 0
  },
  "timeFrom": "2025-08-11T14:50:22.272035+00:00",
  "timeTo": "2025-08-12T14:50:35.980820+00:00"
}

Specific Job Response

{
  "jobId": "4eb23b8c-8d50-4a39-9bb1-490d8e6df521",
  "jobType": "BULK",
  "jobStatus": "COMPLETED",
  "platformData": {},
  "totalItems": 3,
  "processedItems": 3,
  "failedItems": 0,
  "skippedItems": 0,
  "conflictItems": 0,
  "errorMessage": null,
  "failedItemsDetails": {},
  "errorSummary": {},
  "skippedItemsDetails": {},
  "skippedSummary": {},
  "conflictDetails": {},
  "conflictSummary": {},
  "createdAt": "2025-08-12T14:50:22.272035+00:00",
  "startedAt": "2025-08-12T14:50:24.936806+00:00",
  "completedAt": "2025-08-12T14:50:35.980820+00:00",
  "progressPercentage": 100.0,
  "estimatedTimeMinutes": 1
}

Workflow Example

Here's a typical workflow for adding products and monitoring the job:

1. Add Products (Returns Job ID)

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/documents \
    -H "Authorization: Bearer {api_key}" \
    -H "Content-Type: application/json" \
    -d '{"documents": [
{
    "_id": "light-blue-shirt",
    "parentProductId": "parent-shirt", 
    "productTitle": "Shirt",
    "variantTitle": "Shirt - Light Blue",
    "variantImageUrl": "https://cdn.shopify.com/s/files/1/0705/8276/3687/files/light-blue-tshirt.jpg?v=1754569578",
    "price": 100,
    "color": "Light Blue",
    "productCollections": ["shirts"]
}
]}'

Response:

{
  "jobId": "4eb23b8c-8d50-4a39-9bb1-490d8e6df521"
}

2. Check Job Status

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/jobs/4eb23b8c-8d50-4a39-9bb1-490d8e6df521 \
-H "Authorization: Bearer {api_key}"

3. Monitor Until Complete

Keep checking the job status until it shows COMPLETED. Check the failedItems count to see if any documents failed processing.

Best Practices

Job Monitoring

Check Status Regularly: Monitor job progress, especially for large batches
Handle Failures: Check failed jobs for error details and retry if needed
Batch Appropriately: Keep document batches to 25-75 documents for optimal performance

Error Handling

Parse Error Messages: Failed jobs contain detailed error information
Retry Failed Operations: Fix issues and resubmit failed documents
Validate Before Submitting: Ensure documents meet all requirements