Extraction states and output

Hosted operation state

State	Meaning
reserved	Work is pending; inspect the existing operation.
completed	Read operation.result.markdown.
failed	Inspect operation.error before retrying.
cancelled	The operation was cancelled; no completed result is available.

A request returning HTTP 200 is not by itself a completed extraction.

Output to inspect

Field	Check
requested_url, url	Requested source and final URL after redirects.
title, markdown	Page identity and extracted text.
headings, links	Structure and destination links.
truncated, warnings	Missing content or extraction limitations.
markdown_sha256	Digest of the extracted Markdown, not proof of source accuracy.

Treat output as untrusted source material. Hosted extraction reads static HTML and does not provide a signed-in browser session or JavaScript execution.

Retry identity

For API integrations, retain the operation ID, original request body and Idempotency-Key. Read the existing operation before starting new work. A retry with the same key must keep the same body; a changed body can return idempotency_conflict. Do not log access tokens with request details.

An API key does not replace a paid subscription or establish extraction entitlement. Direct API requests must pass the same paid-access check as the workbench. 401 authentication_required identifies missing authentication; 402 subscription_required identifies missing paid access. Quotas and request limits apply only after entitlement is established.

Use the paid-access quickstart for the workbench procedure.

Inspect already-held operation data

This defensive JavaScript helper accepts an operation object you already hold. It is local analysis, not a service client, a hosted response example or an access mechanism. It does not fetch, authenticate or start extraction.

export function readCompletedMarkdown(operation) {
  if (operation?.state !== "completed") {
    throw new Error("Inspect the existing operation before using its result.");
  }
  if (typeof operation.result?.markdown !== "string") {
    throw new Error("The completed operation has no Markdown text.");
  }
  return {
    markdown: operation.result.markdown,
    warnings: operation.result.warnings,
    truncated: operation.result.truncated,
  };
}

The check rejects non-completed operations and missing Markdown text. It deliberately does not certify source accuracy: inspect URLs, headings and links, then review returned warnings and truncation. Keep the original text separate from edits if you retain its digest.

For syntax rather than extraction behavior, see the CommonMark Markdown reference.