---
title: "POST /v1/url-estimates"
method: POST
path: "/v1/url-estimates"
tags: ["Conversion"]
---

# POST /v1/url-estimates

`POST /v1/url-estimates`

## Request

- Base URL: `https://markovo.net`
- URL: `https://markovo.net/v1/url-estimates`
- Auth: one of:
  - HTTP bearer
  - none

Fetch one supported public source after explicit caller consent. Supports public HTML/text, Google Docs, Notion pages and bounded databases, GitHub text resources and discussions, Hacker News, and downloadable YouTube audio. No private/login-only sources, Tencent Docs account connection, browser rendering, generic binary downloads, or remote document images. Ordinary documents use URL fetch-time/word billing; YouTube uses audio-to-markdown duration billing (0.5 Credit/minute, minimum 0.3), at most one hour and 32 MB within the account upload limit. Anonymous estimates return job_token for the bounded guest-preview-session flow; authenticated callers confirm with JSON upload_id and a Credit ceiling at POST /v1/jobs. Guest downloads require sign-in, claim, and account settlement.

## Request body

- object
  - `url` string, required: A public HTTPS link. The server normalizes bare domains and HTTP links to HTTPS; use a full HTTPS URL for portable clients. Never include credentials.
  - `accept_remote_fetch` true, required

## Response `201`

Bounded public-source estimate; YouTube adds source_kind=youtube_audio and duration_ms. Anonymous requests also receive job_token.

- Estimate
  - `upload_id` string, required
  - `job_token` string: Anonymous estimate ownership token. Keep it private; URL guest previews submit it with upload_id to POST /v1/guest-preview-sessions.
  - `capability_id` string
  - `filename` string
  - `source_units_estimated` integer
  - `source_kind` 'youtube_audio'
  - `duration_ms` integer: Present for YouTube audio estimates; billing uses decoded duration.
  - `expires_at` string, date-time
  - `credit_scale` unknown, required
  - `credit_model_version` string, required
  - `rate_card_version` string, required
  - `estimated_credit_units` integer, required
  - `estimated_credits` number
  - `layout_fidelity` 'standard' | 'formula'
  - `formula_detection` object: Present when formula enhancement was requested but local preflight found no formula region. The estimate automatically uses standard conversion and adds no formula charge.
    - `requested` unknown, required
    - `applied` unknown, required
    - `reason` 'no_formula_regions', required
    - `additional_credit_units` unknown, required
  - `formula_candidate_pages` integer[]
  - `formula_regions` object[]: Regions detected during unpaid formula preflight; the estimate shows the region count and maximum price before conversion.
    - `region_id` string, required
    - `page_index` integer, required
    - `bbox` number[], required
  - `external_processing` object: When required, only the detected formula region is transferred to a third-party service; the scope is disclosed before conversion.
    - `required` boolean
    - `transfer_scope` string
  - `page_ranges` string: Normalized page selection echoed for pdf-to-markdown when the request included pages, e.g. "1-3,5,8-12".
  - `pages_selected` integer: Number of source pages the estimate prices when a page selection applies.
  - `source_pages_total` integer: Real document page count a page selection was validated against.
  - `billing_metrics` object

## Other responses

- `400`: Machine-readable safe error
- `401`: Machine-readable safe error
- `403`: Machine-readable safe error
- `413`: Machine-readable safe error
- `422`: Machine-readable safe error
- `503`: Machine-readable safe error

---

[API](https://skmtc.dev/markovo/apis/markovo-conversion-api.md) · [All operations](https://skmtc.dev/markovo/apis/markovo-conversion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/markovo/apis/markovo-conversion-api/revisions/e080e7b85e2e?raw)