Get Results

Retrieve conversion result artifacts once a conversion task has completed successfully.

Endpoint

GET /v1/result/{task_id}

Authentication

All requests require authentication using the X-Api-Key header with your API key.

Path Parameters

Request Headers

Response

Success Response (200 OK)

By default, the endpoint returns one result item per input document. Each result item contains result artifacts, including a download URL for each converted output:

{
  "documents": [
    {
      "filename": "2311.18481",
      "source_index": 0,
      "source_uri": "https://arxiv.org/pdf/2311.18481",
      "status": "success",
      "errors": [],
      "timings": {},
      "artifacts": [
        {
          "artifact_type": "markdown",
          "mime_type": "text/markdown",
          "uri": "https://...",
          "url_expires_at": "2026-06-15T12:00:00Z"
        }
      ]
    }
  ],
  "num_converted": 1,
  "num_succeeded": 1,
  "num_partially_succeeded": 0,
  "num_failed": 0,
  "processing_time": 2.2357177734375
}

Document Result Object

Each item in documents describes the conversion result for one source:

Artifact Object

Each artifact describes one converted output format:

Task Failure Result

If the task itself fails, /v1/result/{task_id} returns a task-level failure object instead of documents. This shape is reserved for internal failures that affect the task as a whole. User input problems should normally be rejected during request validation or reported as document-level failures.

{
  "kind": "TaskFailureResult",
  "failure": {
    "category": "internal",
    "message": "Internal processing error.",
    "retryable": false,
    "phase": "execution",
    "details": {
      "task_size": "1",
      "target_kind": "presigned_url"
    }
  }
}

Document-Level Failures

A task can complete with task_status: "success" even if one or more documents failed conversion. In that case, the result includes counters such as num_failed, and failed document entries have a failure status. For source conversion, an unreachable source is reported as a document-level failure so other reachable sources in the same request can still succeed.

Error Responses

See Error Handling for the full error model.

Examples

Find examples of using the Results endpoint in the Examples section.

Output Format Details

Markdown Format

When you request the markdown format, the result contains a markdown artifact. Download the artifact from its uri to get content with:

• Document structure (headings, paragraphs)
• Tables in Markdown table format
• Lists (ordered and unordered)
• Code blocks
• Images (embedded or referenced, based on image_export_mode)
• Mathematical formulas in LaTeX format

Example:

# Document Title

## Section 1

This is a paragraph with **bold** and *italic* text.

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

$$E = mc^2$$

JSON Format

When you request the json format, the result contains a json artifact with the full DoclingDocument — Docling's structured representation of the document. It preserves reading order and typed elements (text items, tables, pictures, groups) along with page and origin metadata, rather than a flat string.

This is the same structure returned by the Python SDK's result.document.export_to_dict(). For the complete schema and field descriptions, see the DoclingDocument reference. To work with individual elements (for example, extracting only tables), see Specific Extraction.

HTML Format

When you request the html format, the result contains an html artifact with:

• Semantic HTML5 markup
• Styled tables
• Preserved document structure
• Embedded or referenced images

Result Retention

Conversion result artifacts are retained for TODO: confirm retention period after a task completes, then automatically deleted. You can retrieve results multiple times within that window. Download URLs expire separately at url_expires_at; download and store artifacts promptly.

Common Issues

Result not found (404) — the result isn't available. Usually the task is still processing or has failed: check /v1/status/poll/{task_id} first and retrieve the result only once the status is success. The result may also have expired (see Result Retention).

Incomplete content — check the document-level errors array for non-fatal warnings, confirm the source isn't corrupted, and try a different output format. Include the task_id if you contact support.

Task failure result — if the response has kind: "TaskFailureResult", inspect the failure object for category, message, retryable, phase, and details. This indicates a task-level failure, not an ordinary per-document input error.

Document-level failures — if num_failed is greater than zero, inspect each item in documents for its status.

Large results — stream downloaded artifacts to files rather than loading artifact content into memory.

Best Practices

1. Check status first - Retrieve results after the task status is success; if the task status is failure, inspect the failure and error_message fields instead
2. Inspect result counters - Check num_failed and each document's status
3. Store results promptly - Download and save results within your plan's retention window
4. Request only what you need - Choose the output format(s) that suit your use case
5. Monitor processing time - Use the processing_time field to track performance

Rate Limits

See Rate Limits for the default limits and 429 handling.

Related Endpoints

• Convert Source - Convert documents from URLs
• Convert File - Upload and convert local files
• Poll Status - Check conversion progress