Crawl Result and Output

When you call arun() on a page, Crawl4AI returns a CrawlResult object containing everything you might need—raw HTML, a cleaned version, optional screenshots or PDFs, structured extraction results, and more. This document explains those fields and how they map to different output types.

1. The `CrawlResult` Model

Below is the core schema. Each field captures a different aspect of the crawl’s result:

class MarkdownGenerationResult(BaseModel):
    raw_markdown: str
    markdown_with_citations: str
    references_markdown: str
    fit_markdown: Optional[str] = None
    fit_html: Optional[str] = None

class CrawlResult(BaseModel):
    url: str
    html: str
    success: bool
    cleaned_html: Optional[str] = None
    media: Dict[str, List[Dict]] = {}
    links: Dict[str, List[Dict]] = {}
    downloaded_files: Optional[List[str]] = None
    screenshot: Optional[str] = None
    pdf : Optional[bytes] = None
    markdown: Optional[Union[str, MarkdownGenerationResult]] = None
    markdown_v2: Optional[MarkdownGenerationResult] = None
    extracted_content: Optional[str] = None
    metadata: Optional[dict] = None
    error_message: Optional[str] = None
    session_id: Optional[str] = None
    response_headers: Optional[dict] = None
    status_code: Optional[int] = None
    ssl_certificate: Optional[SSLCertificate] = None
    class Config:
        arbitrary_types_allowed = True

Table: Key Fields in `CrawlResult`

Field (Name & Type)	Description
url (`str`)	The final or actual URL crawled (in case of redirects).
html (`str`)	Original, unmodified page HTML. Good for debugging or custom processing.
success (`bool`)	`True` if the crawl completed without major errors, else `False`.
cleaned_html (`Optional[str]`)	Sanitized HTML with scripts/styles removed; can exclude tags if configured via `excluded_tags` etc.
media (`Dict[str, List[Dict]]`)	Extracted media info (images, audio, etc.), each with attributes like `src`, `alt`, `score`, etc.
links (`Dict[str, List[Dict]]`)	Extracted link data, split by `internal` and `external`. Each link usually has `href`, `text`, etc.
downloaded_files (`Optional[List[str]]`)	If `accept_downloads=True` in `BrowserConfig`, this lists the filepaths of saved downloads.
screenshot (`Optional[str]`)	Screenshot of the page (base64-encoded) if `screenshot=True`.
pdf (`Optional[bytes]`)	PDF of the page if `pdf=True`.
markdown (`Optional[str or MarkdownGenerationResult]`)	For now, `markdown_v2` holds a `MarkdownGenerationResult`. Over time, this will be consolidated into `markdown`. The generator can provide raw markdown, citations, references, and optionally `fit_markdown`.
markdown_v2 (`Optional[MarkdownGenerationResult]`)	Legacy field for detailed markdown output. This will be replaced by `markdown` soon.
extracted_content (`Optional[str]`)	The output of a structured extraction (CSS/LLM-based) stored as JSON string or other text.
metadata (`Optional[dict]`)	Additional info about the crawl or extracted data.
error_message (`Optional[str]`)	If `success=False`, contains a short description of what went wrong.
session_id (`Optional[str]`)	The ID of the session used for multi-page or persistent crawling.
response_headers (`Optional[dict]`)	HTTP response headers, if captured.
status_code (`Optional[int]`)	HTTP status code (e.g., 200 for OK).
ssl_certificate (`Optional[SSLCertificate]`)	SSL certificate info if `fetch_ssl_certificate=True`.

2. HTML Variants

`html`: Raw HTML

Crawl4AI preserves the exact HTML as result.html. Useful for:

Debugging page issues or checking the original content.
Performing your own specialized parse if needed.

`cleaned_html`: Sanitized

If you specify any cleanup or exclusion parameters in CrawlerRunConfig (like excluded_tags, remove_forms, etc.), you’ll see the result here:

config = CrawlerRunConfig(
    excluded_tags=["form", "header", "footer"],
    keep_data_attributes=False
)
result = await crawler.arun("https://example.com", config=config)
print(result.cleaned_html)  # Freed of forms, header, footer, data-* attributes

3. Markdown Generation

3.1 `markdown_v2` (Legacy) vs `markdown`

markdown_v2: The current location for detailed markdown output, returning a MarkdownGenerationResult object.
markdown: Eventually, we’re merging these fields. For now, you might see result.markdown_v2 used widely in code examples.

MarkdownGenerationResult Fields:

Field	Description
raw_markdown	The basic HTML→Markdown conversion.
markdown_with_citations	Markdown including inline citations that reference links at the end.
references_markdown	The references/citations themselves (if `citations=True`).
fit_markdown	The filtered/“fit” markdown if a content filter was used.
fit_html	The filtered HTML that generated `fit_markdown`.

3.2 Basic Example with a Markdown Generator

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator

config = CrawlerRunConfig(
    markdown_generator=DefaultMarkdownGenerator(
        options={"citations": True, "body_width": 80}  # e.g. pass html2text style options
    )
)
result = await crawler.arun(url="https://example.com", config=config)

md_res = result.markdown_v2  # or eventually 'result.markdown'
print(md_res.raw_markdown[:500])
print(md_res.markdown_with_citations)
print(md_res.references_markdown)

Note: If you use a filter like PruningContentFilter, you’ll get fit_markdown and fit_html as well.

4. Structured Extraction: `extracted_content`

If you run a JSON-based extraction strategy (CSS, XPath, LLM, etc.), the structured data is not stored in markdown—it’s placed in result.extracted_content as a JSON string (or sometimes plain text).

Example: CSS Extraction with `raw://` HTML

import asyncio
import json
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode
from crawl4ai.extraction_strategy import JsonCssExtractionStrategy

async def main():
    schema = {
        "name": "Example Items",
        "baseSelector": "div.item",
        "fields": [
            {"name": "title", "selector": "h2", "type": "text"},
            {"name": "link", "selector": "a", "type": "attribute", "attribute": "href"}
        ]
    }
    raw_html = "<div class='item'><h2>Item 1</h2><a href='https://example.com/item1'>Link 1</a></div>"

    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(
            url="raw://" + raw_html,
            config=CrawlerRunConfig(
                cache_mode=CacheMode.BYPASS,
                extraction_strategy=JsonCssExtractionStrategy(schema)
            )
        )
        data = json.loads(result.extracted_content)
        print(data)

if __name__ == "__main__":
    asyncio.run(main())

Here: - url="raw://..." passes the HTML content directly, no network requests.
- The CSS extraction strategy populates result.extracted_content with the JSON array [{"title": "...", "link": "..."}].

5. More Fields: Links, Media, and More

5.1 `links`

A dictionary, typically with "internal" and "external" lists. Each entry might have href, text, title, etc. This is automatically captured if you haven’t disabled link extraction.

print(result.links["internal"][:3])  # Show first 3 internal links

5.2 `media`

Similarly, a dictionary with "images", "audio", "video", etc. Each item could include src, alt, score, and more, if your crawler is set to gather them.

images = result.media.get("images", [])
for img in images:
    print("Image URL:", img["src"], "Alt:", img.get("alt"))

5.3 `screenshot` and `pdf`

If you set screenshot=True or pdf=True in CrawlerRunConfig, then:

result.screenshot contains a base64-encoded PNG string.
result.pdf contains raw PDF bytes (you can write them to a file).

with open("page.pdf", "wb") as f:
    f.write(result.pdf)

5.4 `ssl_certificate`

If fetch_ssl_certificate=True, result.ssl_certificate holds details about the site’s SSL cert, such as issuer, validity dates, etc.

6. Accessing These Fields

After you run:

result = await crawler.arun(url="https://example.com", config=some_config)

Check any field:

if result.success:
    print(result.status_code, result.response_headers)
    print("Links found:", len(result.links.get("internal", [])))
    if result.markdown_v2:
        print("Markdown snippet:", result.markdown_v2.raw_markdown[:200])
    if result.extracted_content:
        print("Structured JSON:", result.extracted_content)
else:
    print("Error:", result.error_message)

Remember: Use result.markdown_v2 for now. It will eventually become result.markdown.

7. Next Steps

Markdown Generation: Dive deeper into how to configure DefaultMarkdownGenerator and various filters.
Content Filtering: Learn how to use BM25ContentFilter and PruningContentFilter.
Session & Hooks: If you want to manipulate the page or preserve state across multiple arun() calls, see the hooking or session docs.
LLM Extraction: For complex or unstructured content requiring AI-driven parsing, check the LLM-based strategies doc.

Enjoy exploring all that CrawlResult offers—whether you need raw HTML, sanitized output, markdown, or fully structured data, Crawl4AI has you covered!

Crawl Result and Output

1. The CrawlResult Model

Table: Key Fields in CrawlResult

2. HTML Variants

html: Raw HTML

cleaned_html: Sanitized

3. Markdown Generation

3.1 markdown_v2 (Legacy) vs markdown