---
title: "Estimate credits"
description: "Price a conversion before running it: POST https://api.markitdown.ai/v1/convert/{name}/estimate takes the submit body and returns pages and credits per source without charging anything."
url: https://markitdown.ai/docs/api/estimates
updated: 2026-09-26
source: markitdown.ai
---

# Estimate credits

> Price a conversion before running it: POST https://api.markitdown.ai/v1/convert/{name}/estimate takes the submit body and returns pages and credits per source without charging anything.

## What an estimate does

Every convert endpoint has an estimate twin at the same path plus `/estimate`. It accepts exactly the request body the submit endpoint accepts, reads each source to count its pages, and returns the credits the conversion would cost. It never creates a conversion, never reserves or spends credits, and deletes anything it had to stage to read the source.

Markdown to HTML and Markdown to Text cost no credits, so their estimates always return `0`; they exist so one client can price any conversion the same way.

## Estimate endpoints

| Conversion | Estimate endpoint |
| --- | --- |
| [Excel to Markdown](/docs/api/convert-excel) | `POST /v1/convert/excel/estimate` |
| [HTML to Markdown](/docs/api/convert-html) | `POST /v1/convert/html/estimate` |
| [Image to Markdown](/docs/api/convert-image) | `POST /v1/convert/image/estimate` |
| [Markdown to HTML](/docs/api/convert-markdown-html) | `POST /v1/convert/markdown/html/estimate` |
| [Markdown to Text](/docs/api/convert-markdown-text) | `POST /v1/convert/markdown/text/estimate` |
| [PDF to Markdown](/docs/api/convert-pdf) | `POST /v1/convert/pdf/estimate` |
| [PowerPoint to Markdown](/docs/api/convert-powerpoint) | `POST /v1/convert/powerpoint/estimate` |
| [Text to Markdown](/docs/api/convert-text) | `POST /v1/convert/text/estimate` |
| [URL to Markdown](/docs/api/convert-url) | `POST /v1/convert/url/estimate` |
| [Word to Markdown](/docs/api/convert-word) | `POST /v1/convert/word/estimate` |

## Request

Send the body you would send to the submit endpoint: a multipart `file` or `files`, JSON `url`/`urls`, `text`/`texts`, or references to earlier files and completed uploads. Options such as `pages` or `ocr` change the estimate the same way they change the conversion.

**Estimate a PDF**

```bash
curl -X POST https://api.markitdown.ai/v1/convert/pdf/estimate \
  -H "x-api-key: $MARKITDOWN_API_KEY" \
  -F file=@report.pdf
```

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sources[]` | array | yes | One entry per source, in request order: `name`, `pages` and `credits`. |
| `credits_total` | integer | yes | Sum of `credits` across all sources. |
| `balance` | integer | yes | The account's current credit balance, so you can compare it with `credits_total`. |

**200 example**

```json
{
  "sources": [
    {
      "name": "report.pdf",
      "pages": 12,
      "credits": 12
    }
  ],
  "credits_total": 12,
  "balance": 1500
}
```

## What an estimate does not check

- Plan limits. The per-file size limit, the page cap, the monthly file allowance and storage are checked only when you submit, so an estimate can succeed for a file the submit endpoint then rejects.
- Your balance. The estimate returns `balance` but does not fail when `credits_total` is higher; the submit endpoint returns `402 insufficient_credits` in that case.
- Scope and subscription do apply: an estimate needs the `read` scope (a read-only key can price conversions) and an active Lite, Pro or Max subscription; otherwise it returns `403 scope_missing` or `403 subscription_required`.

## Related

- [API reference](https://markitdown.ai/docs/api)
- [Error codes](https://markitdown.ai/docs/errors)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)