# Mixedbread Parsing

> Parse documents, extract structured content, and run OCR using the Mixedbread Parsing API. Use when parsing PDFs, Word documents, PowerPoint slides, or images, extracting tables or form fields, running OCR on scanned documents, converting documents to markdown or HTML, or extracting structured chunks with element-level bounding boxes and confidence scores.

- Skill: `mixedbread-ai/mixedbread-parsing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mixedbread-ai/mixedbread-parsing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mixedbread-ai/mixedbread-parsing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: mixedbread-ai (https://skillmd.com/u/mixedbread-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mixedbread-ai/mixedbread-parsing

---


# Mixedbread Parsing

Parse documents, extract structured content, and run OCR using the Parsing API. Supports PDFs, Word documents, PowerPoint presentations, and images.

Docs: https://www.mixedbread.com/docs/parsing/overview.md
Agent-readable docs: https://www.mixedbread.com/docs/llms.txt
Latest docs search: https://www.mixedbread.com/question?q=parsing&section=docs

## Setup

```bash
pip install mixedbread          # Python
npm install @mixedbread/sdk     # TypeScript
```

```bash
export MXBAI_API_KEY=your_api_key
```

## Quick Start

**Python:**
```python
from mixedbread import Mixedbread

mxbai = Mixedbread()

# Upload and parse a document (waits for completion)
job = mxbai.parsing.jobs.upload_and_poll(
    file=open("report.pdf", "rb"),
    return_format="markdown",
)

for chunk in job.result.chunks:
    print(chunk.content)
```

**TypeScript:**
```typescript
import Mixedbread from '@mixedbread/sdk';
import fs from 'fs';

const mxbai = new Mixedbread();

const job = await mxbai.parsing.jobs.uploadAndPoll(
    fs.createReadStream('report.pdf'),
    { return_format: 'markdown' },
);

for (const chunk of job.result.chunks) {
    console.log(chunk.content);
}
```

## Decision Tree

- **Which convenience method?**
  - File on disk → `upload_and_poll()` (uploads + creates job + polls)
  - File already uploaded via Files API → `create_and_poll()` (creates job + polls)
  - Need async control → `upload()` or `create()` then `poll()` separately
- **Which parsing mode?** (default is `high_quality`)
  - Born-digital PDF (selectable text) → pass `mode="fast"` explicitly. Fastest, lowest cost. Extracts text, structure, and layout.
  - Scanned document, image, or complex layout → `high_quality` mode (the default). Uses OCR. Extracts text with confidence scores and per-element bounding boxes, handles rotated/skewed pages, multi-column layouts.
- **Which return format?** → `return_format`: `markdown` (default), `html`, or `plain`
- **Need specific elements only?** → Set `element_types` to reduce processing time

## Supported File Types

PDF (`.pdf`), Word (`.doc`, `.docx`, `.dotx`, `.docm`, `.dotm`, `.odt`, `.rtf`), Slides (`.ppt`, `.pptx`, `.ppsx`, `.ppam`, `.pptm`, `.potm`, `.ppsm`, `.odp`), Images (`.jpeg`, `.png`, `.webp`, `.avif`).

Element types: `text`, `title`, `section-header`, `header`, `footer`, `page-number`, `list-item`, `figure`, `table`, `form`, `footnote`. (Legacy values `picture`, `caption`, `formula`, `page-header`, and `page-footer` are accepted but normalized to `figure`/`text`/`header`/`footer`.)

Each extracted element carries `type`, `content`, `page`, `confidence` (0–1), and `bbox` — the bounding box `[x1, y1, x2, y2]` in page pixel coordinates. Use bboxes to map OCR output back to its location on the page (e.g. evidence highlighting).

Chunking: `chunking_strategy` defaults to `page` (currently the only strategy) — one chunk per page.

## Workflows

### Extract Tables from Documents

Filter for table elements to pull structured data from reports.

**Python:**
```python
job = mxbai.parsing.jobs.upload_and_poll(
    file=open("financial-report.pdf", "rb"),
    element_types=["table"],
    return_format="html",
    mode="high_quality",
)
for chunk in job.result.chunks:
    for element in chunk.elements:
        if element.type == "table":
            print(f"Page {element.page}, confidence {element.confidence:.2f}, bbox {element.bbox}")
            print(element.content)
```

**TypeScript:**
```typescript
const job = await mxbai.parsing.jobs.uploadAndPoll(
    fs.createReadStream('financial-report.pdf'),
    { element_types: ['table'], return_format: 'html', mode: 'high_quality' },
);
for (const chunk of job.result.chunks) {
    for (const element of chunk.elements) {
        if (element.type === 'table') {
            console.log(`Page ${element.page}, confidence ${element.confidence.toFixed(2)}, bbox ${element.bbox}`);
            console.log(element.content);
        }
    }
}
```

### Batch Parse Multiple Files

Upload multiple files asynchronously, then poll all jobs:

**Python:**
```python
import os

jobs = []
for filename in os.listdir("./documents"):
    if filename.endswith(".pdf"):
        job = mxbai.parsing.jobs.upload(
            file=open(f"./documents/{filename}", "rb"),
            return_format="markdown",
        )
        jobs.append(job)

# Poll all jobs
for job in jobs:
    completed = mxbai.parsing.jobs.poll(job_id=job.id)
    print(f"{completed.filename}: {len(completed.result.chunks)} chunks")
```

**TypeScript:**
```typescript
import { readdirSync, createReadStream } from 'fs';
import path from 'path';

const files = readdirSync('./documents').filter(f => f.endsWith('.pdf'));
const jobs = await Promise.all(
    files.map(f => mxbai.parsing.jobs.upload(
        createReadStream(path.join('./documents', f)),
        { return_format: 'markdown' },
    )),
);

// Poll all jobs
for (const job of jobs) {
    const completed = await mxbai.parsing.jobs.poll(job.id);
    console.log(`${completed.filename}: ${completed.result.chunks.length} chunks`);
}
```

## Rules

### CRITICAL
- **Don't double-parse.** Store uploads auto-parse documents. Files uploaded with `parsing_strategy: "high_quality"` automatically get OCR text (images), summaries (images), and transcriptions (audio & video) extracted. These are available as fields on search result chunks. There is no benefit to also running the Parsing API on the same file. Use the Parsing API only for standalone document extraction outside of stores.
- **Use `upload_and_poll()` / `create_and_poll()` instead of manual polling loops.** These methods handle backoff automatically. Manual `while` loops with `retrieve()` are fragile and waste API calls.

### HIGH
- **Specify `element_types` when you only need certain elements.** Requesting all types increases processing time and response size. If you only need tables, set `element_types` to `table` only.
- **Use `fast` mode for born-digital PDFs.** The `high_quality` mode adds OCR overhead that provides no benefit when text is already selectable.
- **Check `confidence` scores on OCR output.** Low-confidence elements (< 0.5) may contain errors. Filter or flag them.

### MEDIUM
- **Check `job.error` before retrying failed jobs.** Common causes: unsupported file type, corrupt file, file too large. Blindly retrying wastes quota.
- **Use `content_to_embed` for embedding pipelines.** Each chunk provides both `content` (full text) and `content_to_embed` (optimized for embedding). Use the latter when feeding into vector stores outside Mixedbread.
- **Verify file format before parsing.** Only PDF, Word, PowerPoint, and images are supported. Convert other formats first.

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Job stuck in `pending` | Queue is busy | Use `poll()` with a longer `poll_timeout_ms`. Check job status with `retrieve()`. |
| Job status `failed` | Unsupported file type, corrupt file, or file too large | Check `job.error` for details. Verify file format is supported. |
| Empty chunks in result | File has no extractable content (blank pages) | Verify the file has content. Try `high_quality` mode for scanned documents. |
| Low confidence scores | Scanned or low-resolution source | Use `high_quality` mode for better OCR accuracy. |
| Missing tables or figures | Element types not requested | Set `element_types` to include `table` and `figure` explicitly. |
| `upload_and_poll()` timeout | Very large document or slow processing | Increase `poll_timeout_ms`, or use `upload()` + `poll()` separately for more control. |