---
title: "Conversions"
description: "List, wait on, stream, retry, and delete v1 conversions, and how conversion and file statuses behave."
url: https://markitdown.ai/docs/conversions
updated: 2026-09-25
source: markitdown.ai
---

# Conversions

> List, wait on, stream, retry, and delete v1 conversions, and how conversion and file statuses behave.

## List and get

**GET** `/v1/conversions` — List conversions

**GET** `/v1/conversions/{id}` — Get a conversion; `?wait=N` long-polls up to 100 seconds

`GET /v1/conversions` pages with the opaque `next_cursor` it returns (pass it back as `cursor`). Each item is the same envelope `POST /v1/convert/{name}` returns, without the `files` list.

## Files and content

**GET** `/v1/conversions/{id}/files` — List every source file and its outputs, optionally filtered by status

Page through this when a conversion has more than the 100 source files inlined in `GET /v1/conversions/{id}`. Read a finished output with `GET /v1/conversions/{id}/files/{file_id}/content`, which streams the raw bytes by the file's own MIME type — no JSON envelope to unwrap.

## Live progress (SSE)

**GET** `/v1/conversions/{id}/events` — Server-sent events for one conversion

The stream sends `event: file` with `{ file_id, status }` as each source file changes state, `event: conversion` with the summary envelope when the overall status or counts change, then a final `event: conversion` and `event: end` once the conversion reaches a terminal status. It replays the current snapshot on connect, so a late subscriber never misses the outcome.

## Delete and retry

**DELETE** `/v1/conversions/{id}` — Delete a conversion and every file it holds

**POST** `/v1/conversions/{id}/files/{file_id}/retry` — Re-run one failed source file — always 202

Deleting removes the conversion record and its stored files. It does not interrupt a source file that is already parsing, but any file that has not started yet is settled as failed and refunded instead of running. Retry only accepts a `failed` source file; it re-reserves that file's credits and moves the conversion back to `running`.

## What statuses can a conversion report?

A conversion is `queued`, then `running` while at least one source file is still working, and then a terminal status: `completed` (every file succeeded), `completed_with_errors` (some succeeded, some failed), or `failed` (none succeeded) — checking `status` alone never hides a partial failure. A source file's own `error` is a problem object with a stable code such as `document_unprocessable` or `parser_unavailable`; a failed file is not charged. Results are deleted after 24 hours by default; send `store: true` on the submission to keep them in your library for your plan's retention window.

## Should I poll, stream, or use webhooks?

Long polling with `GET /v1/conversions/{id}?wait=100` is the simplest: one request returns as soon as the conversion settles or the wait ends. Use the SSE stream when you show progress to a person, especially for a submission with several source files. Use webhooks for server-side pipelines that should not hold connections open — send many files in one `POST /v1/convert/{name}` call instead of starting many separate conversions.

## Related

- [Convert](https://markitdown.ai/docs/convert)
- [Batches](https://markitdown.ai/docs/batches)
- [Conversion Files](https://markitdown.ai/docs/files)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)