Batch Image Processing (legacy)

Process multiple equation images in a single request.

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, then retrieve results through image results. 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.), processed asynchronously with results delivered to your own cloud storage.

Endpoint	Description
POST v3/batch	Submit a batch of image URLs
GET v3/batch/{batch_id}	Retrieve batch results

See the batch processing guide for step-by-step examples.

POST v3/batch

POST api.mathpix.com/v3/batch

The request body may contain any v3/latex parameters except src, plus a urls parameter and optional callback.

warning

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

Example

Request body

{
  "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"]
}

cURL

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

Python

import requests
base_url = "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/"
r = requests.post("https://api.mathpix.com/v3/batch",
    json={
        "urls": {
            "algebra": base_url + "algebra.jpg",
            "inverted": base_url + "inverted.jpg"
        },
        "formats": ["latex_simplified"]
    },
    headers={
        "app_id": "APP_ID",
        "app_key": "APP_KEY",
        "content-type": "application/json"
    },
    timeout=30
)
print(r.json())  # {"batch_id": 17}

JavaScript / TypeScript

const base = "https://raw.githubusercontent.com/Mathpix/api-examples/master/images/";
const response = await fetch("https://api.mathpix.com/v3/batch", {
  method: "POST",
  headers: {
    app_id: "APP_ID",
    app_key: "APP_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: {
      inverted: base + "inverted.jpg",
      algebra: base + "algebra.jpg",
    },
    formats: ["latex_simplified"],
  }),
});
const { batch_id } = await response.json();
console.log(`Batch ID: ${batch_id}`);

Go

body := bytes.NewBufferString(`{
    "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"]
}`)
req, _ := http.NewRequest("POST", "https://api.mathpix.com/v3/batch", body)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result)) // {"batch_id": 17}

Java

HttpClient client = HttpClient.newHttpClient();
String body = """
    {
      "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"]
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/batch"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Example response

{
  "batch_id": 17
}

Request parameters

urls object

key-value for each image in the batch where the value may be a string url or an object containing a url and image-specific options such as region and formats.

ocr_behavior string (optional), default value is latex

"text" for processing like v3/text or "latex" for processing like v3/latex. Only these two values are accepted.

callback Callback (optional)

Description of where to send the batch results.

metadata object (optional)

Key-value object. Supports improve_mathpix for extra privacy controls.

When using ocr_behavior: "text", all v3/text params can be set at the top level or individually per URL.

Response body

batch_id number

Unique batch tracking ID

GET v3/batch/{batch_id}

GET api.mathpix.com/v3/batch/{batch_id}

Retrieve batch results. Wait approximately one second per five images before polling. The GET request must contain the same app_id and app_key headers as the POST.

Example

cURL

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

Python

import requests
r = requests.get("https://api.mathpix.com/v3/batch/BATCH_ID",
    headers={"app_id": "APP_ID", "app_key": "APP_KEY"}
)
print(r.json())  # {"keys": [...], "results": {...}}

JavaScript / TypeScript

const response = await fetch("https://api.mathpix.com/v3/batch/BATCH_ID", {
  headers: { app_id: "APP_ID", app_key: "APP_KEY" },
});
const results = await response.json();
console.log(results);

Go

req, _ := http.NewRequest("GET", "https://api.mathpix.com/v3/batch/BATCH_ID", nil)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result))

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/batch/BATCH_ID"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

keys string[]

all the url keys present in the originating batch request

results object

an OCR result for each key that has been processed

Before completion, the results field may be empty or contain only some results.