Skip to main content

Batch Image Processing (legacy)

Process multiple images in a single request. This endpoint is for images only - for multi-page documents use document processing instead.

Legacy endpoint, images only

v3/batch accepts images only. It cannot process PDFs or any other document, and submitting one will not work.

We do not recommend it for new integrations. Existing batch integrations keep working. For many images, use v3/text with the async flag and a tags field. For documents, use v3/pdf, or files/v1 at bulk volumes.

Two batch APIs

Mathpix has two distinct batch endpoints:

  • POST /v3/batch (this page) - batch of images for OCR; submit, then retrieve results by polling GET /v3/batch/{batch_id}.
  • POST /files/v1/jobs - high-throughput, large-scale batch of documents (PDFs, etc.) for large-scale processing. See the Files API Quickstart.
warning

Only use the batch API when your workload is not latency sensitive. For immediate responses use single image endpoints.

Workflow​

  1. Submit a batch of image URLs - returns a batch_id
  2. Poll results with GET /v3/batch/{batch_id} (wait ~1 second per 5 images)
  3. Results contain an OCR result object for each image key

Submit a batch​

Submit a set of image URLs to the v3/batch endpoint:

curl -X POST https://api.mathpix.com/v3/batch \
-H "app_id: APP_ID" \
-H "app_key: APP_KEY" \
-H "Content-Type: application/json" \
--data '{
  "urls": {
    "inverted": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/inverted.jpg",
    "algebra": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/algebra.jpg"
  },
  "formats": ["latex_simplified"]
}'
Example response
{
  "batch_id": 17
}

Use the batch_id to poll for results.

Poll for results​

Wait approximately one second per five images, then poll GET v3/batch/{batch_id} for results:

curl https://api.mathpix.com/v3/batch/17 \
-H "app_id: APP_ID" \
-H "app_key: APP_KEY"

Before completion, results may be empty or partial. When complete:

Example completed batch response
{
  "keys": ["algebra", "inverted"],
  "results": {
    "algebra": {
      "detection_list": [],
      "detection_map": {
        "contains_chart": 0,
        "contains_diagram": 0,
        "contains_graph": 0,
        "contains_table": 0,
        "is_blank": 0,
        "is_inverted": 0,
        "is_not_math": 0,
        "is_printed": 0
      },
      "latex_simplified": "12 + 5 x - 8 = 12 x - 10",
      "latex_confidence": 0.99640350138238,
      "position": {
        "height": 208,
        "top_left_x": 0,
        "top_left_y": 0,
        "width": 1380
      }
    },
    "inverted": {
      "detection_list": ["is_inverted", "is_printed"],
      "latex_simplified": "x ^ { 2 } + y ^ { 2 } = 9",
      "latex_confidence": 0.99982263230866
    }
  }
}

For this example response, each key in results contains a latex_simplified field with the recognized LaTeX. The algebra result renders as:

12+5x−8=12x−1012 + 5 x - 8 = 12 x - 10

The inverted result renders as:

x2+y2=9x^{2} + y^{2} = 9

Use v3/text behavior​

Set the ocr_behavior request parameter to "text" to process images with v3/text behavior instead of the default v3/latex. Options can be set at the top level or per image.

Top-level options​

{
  "urls": {
    "inverted": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/inverted.jpg",
    "algebra": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/algebra.jpg"
  },
  "ocr_behavior": "text",
  "formats": ["text", "html", "data"],
  "data_options": { "include_asciimath": true }
}

Per-image options​

{
  "urls": {
    "inverted": {
      "url": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/inverted.jpg",
      "ocr_behavior": "text",
      "formats": ["text", "html", "data"],
      "data_options": { "include_asciimath": true }
    },
    "algebra": {
      "url": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/algebra.jpg",
      "ocr_behavior": "text",
      "formats": ["text", "html", "data"],
      "data_options": { "include_asciimath": true }
    }
  }
}

Both request formats return the same response:

Example response
{
  "batch_id": 18
}

Use callbacks​

Receive results automatically when the batch completes by including a callback object in the v3/batch request:

{
  "urls": {
    "inverted": "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/inverted.jpg"
  },
  "formats": ["latex_simplified"],
  "callback": {
    "post": "https://your-server.com/webhook",
    "headers": { "Authorization": "Bearer YOUR_TOKEN" }
  }
}
Example response
{
  "batch_id": 18
}
note

Even with a callback, there is no guarantee it will succeed (e.g., due to transient network failure). Always poll as a fallback.

Next steps​