> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runpulse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Metadata

> Recover native properties and deterministic structure from original PDFs, Office files, spreadsheets, presentations, HTML, and images.

Document metadata captures information stored inside the original file, separate
from its visible text. Examples include PDF XMP, Office author and revision
properties, workbook sheet visibility, and camera EXIF.

Pulse reads this information before conversion, rendering, or OCR so those
processing steps cannot erase it.

## Enable Document Metadata

The extension is a single boolean:

```python Python SDK theme={null}
from pulse import Pulse
from pulse.types import ExtractRequestExtensions

client = Pulse(api_key="YOUR_API_KEY")

response = client.extract(
    file_url="https://example.com/report.pdf",
    extensions=ExtractRequestExtensions(
        document_metadata=True,
    ),
)

metadata = response.extensions.document_metadata
print(metadata.file.name)
print(metadata.properties.title)
print(metadata.structure.page_count)
```

`false` or omission disables metadata extraction. There are no nested selectors.
When enabled, Pulse returns the maximum safely recoverable metadata for the
detected format.

## Response Shape

Metadata is returned under `extensions.document_metadata`:

```json theme={null}
{
  "extensions": {
    "document_metadata": {
      "file": {
        "name": "pulse-complex-metadata-10-page.pdf",
        "extension": ".pdf",
        "media_type": "application/pdf",
        "size_bytes": 32506,
        "sha256": "4c306b9246c699682f40e3a9b10066f2d49c7f86c4d326fdb2e195d50ff3e655"
      },
      "properties": {
        "title": "Pulse Complex Metadata Validation Report",
        "authors": [
          "Ritvik Pandey",
          "Pulse Document Intelligence"
        ],
        "subject": "Deterministic extraction of native document metadata",
        "keywords": ["metadata", "xmp", "pdf", "pulse", "validation"],
        "created_at": "2026-01-15T09:30:00-08:00",
        "modified_at": "2026-07-30T14:45:30-07:00",
        "application": "Pulse Metadata Fixture Generator 1.0",
        "producer": "Pulse PDF Assembly Engine"
      },
      "custom": {
        "PulseCaseId": "PULSE-META-10P-2026",
        "Classification": "confidential-test",
        "RetentionYears": "7"
      },
      "structure": {
        "page_count": 10,
        "page_labels": ["i", "ii", "R-1", "R-2", "R-3", "R-4", "R-5", "R-6", "R-7", "R-8"],
        "outline_count": 10,
        "attachment_count": 1,
        "annotation_count": 5,
        "form_field_count": 3
      },
      "format_specific": {
        "pdf_version": "1.7",
        "encrypted": false,
        "tagged": false
      },
      "warnings": []
    }
  }
}
```

Only enabled extensions are included in `response.extensions`. Within the
metadata result, absent fields are omitted rather than returned as `null`.

## Format Behavior

| Input              | Native metadata                          | Deterministic structure                                         |
| ------------------ | ---------------------------------------- | --------------------------------------------------------------- |
| PDF                | Info dictionary, XMP, custom fields      | Pages, labels, sizes, outlines, forms, annotations, attachments |
| DOCX               | Core, application, and custom properties | Declared pages, paragraphs, tables, sections, media             |
| XLSX/XLSM          | Core and custom properties               | Sheets, visibility, active sheet, workbook type                 |
| PPTX               | Core properties                          | Slides, notes, media                                            |
| JPEG/PNG/TIFF/WebP | Common EXIF or text metadata             | Dimensions, DPI, frame count                                    |
| HTML               | Title, standard meta tags, OpenGraph     | Language and canonical URL                                      |
| CSV                | No standard embedded property store      | Encoding, row count, column count                               |

## Operational Notes

* Metadata is evidence supplied by the file, not independently verified truth.
* Read metadata from original bytes before DOCX-to-PDF, spreadsheet, or image
  conversion.
* Metadata parsing failures are non-fatal. Check `warnings` when a source has
  malformed or unsupported metadata.
* Original images may contain sensitive capture timestamps and precise GPS
  coordinates.
* Detailed lists are bounded to keep extraction results and queued jobs a safe
  size. Pulse adds a warning when metadata must be reduced.
* PDFs can declare conflicting Info and XMP values. Pulse normalizes supported
  XMP author and keyword fields and retains the native XMP values in
  `format_specific` for audit.

<CardGroup cols={2}>
  <Card title="Extract API" icon="brackets-curly" href="/api-reference/endpoint/extract#document-metadata">
    View the complete request and response contract.
  </Card>

  <Card title="Processing Parameters" icon="sliders-horizontal" href="/concepts/processing-parameters">
    Compare metadata with other optional Extract settings.
  </Card>
</CardGroup>