---
title: "[Beta] Get AI Metadata for Multiple Documents"
method: POST
path: "/public/beta/documents/ai-metadata"
tags: ["Documents"]
---

# [Beta] Get AI Metadata for Multiple Documents

`POST /public/beta/documents/ai-metadata`

Returns AI metadata for a list of documents in a single request. The batch variant of <a href="#/operations/getDocumentAiMetadata">Get AI Metadata for a Document</a>.

Use this endpoint when you need AI metadata for several documents and want to avoid issuing one request per document. Each `results[]` entry mirrors the per-document outcome of the single-document endpoint.

### Partial-success model

The response is always `200 OK` when the request itself is valid and the caller is authenticated. Per-document outcomes are reported inside `results[]` via a `status` discriminator. A failure for one document (not found, access denied, isolated server-side failure) does not fail the whole request — the response still returns successful entries for the rest.

Per-document `status` values mirror the HTTP semantics of the single-document endpoint:

| Single-document HTTP | Batch `status`             | Notes                                                                              | | -------------------- | -------------------------- | ---------------------------------------------------------------------------------- | | `200`                | `ok`                       | `ai_metadata` carries the same payload as the single-document `200` body.          | | `202`                | `extraction_pending`       | Includes `retry_after` (seconds). Retry the whole batch or just this `document_id`.| | `204`                | `extraction_failed`        | Terminal. Retrying will not help — contact support.                                | | `409`                | `extraction_not_started`   | Typically because the document is not yet completed.                               | | `404`                | `not_found`                | Document does not exist or is deleted.                                             | | `403`                | `access_denied`            | Caller cannot access this specific document.                                       | | _(none — batch only)_| `internal_error`           | Isolated server-side failure for this document. Retrying the affected document is safe. |

Top-level non-`2xx` responses (`400`, `401`, `403`, `429`) are reserved for whole-request failures — for example, request validation, missing or invalid authentication, the caller has no read scope at all, or rate limiting.

> 🚧 **Beta** > > This endpoint is currently in beta and may change without notice.

## Request body

- BatchAIMetadataRequest — Batch request for AI metadata across multiple documents.
  - `document_ids` string[], required — Documents to fetch AI metadata for. Each entry must be a valid document identifier. Duplicates are not allowed.
  - `field_keys` string[] — Optional filter — restrict the response, for each document, to this subset of AI metadata fields, matched by `key` (the human-readable field name returned as `results[].key` by the single-document endpoint, e.g. `Contract value`). Comparison is exact and case-sensitive. Unknown keys are silently ignored. When omitted, every populated field is returned per document.

## Response `200`

The batch was accepted and processed. Per-document outcomes are in `results[]`. Inspect each entry's `status` field to handle success, pending extraction, terminal failure, missing document, or per-document access denial.

- BatchAIMetadataResponse — Per-document AI metadata results. Always returned with HTTP 200 when the request is valid; per-document failures are reported in `results[].status`.
  - `count` integer, required — Number of entries in `results`. Equal to the number of `document_ids` in the request.
  - `results` BatchAIMetadataResult[], required — Per-document outcomes, in the same order as the request's `document_ids`. Each entry's shape depends on its `status`.
    - union — Outcome for a single document in a batch AI metadata request. The concrete shape is selected by the `status` discriminator.
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'ok', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `ai_metadata` AIMetadataResponse, required — Page of AI metadata fields populated for a document.
          - `count` integer, required — Total number of AI metadata fields available for the document across all pages. The current page slice is in `results` and is bounded by `limit` and `offset`.
          - `results` AIMetadataField[], required — AI metadata fields populated for the document. Each entry combines the field definition with the extracted value. Empty when nothing has been extracted yet.
            - `id` string, required — Stable identifier of the metadata field definition. The same identifier appears for the same field across every document.
            - `key` string, required — Human-readable field key (e.g. `Contract value`, `Counterparty name`, `Expiration date`).
            - `field_type` 'single_line' | 'multi_line' | 'date' | 'number' | 'dropdown' | 'checkbox' | 'url' | 'duration' | 'percent' | 'currency' | 'signature_info', required — Data type of an AI metadata field.
            - `settings` object, required — Field-type-specific configuration (e.g. available `period` units for `duration`, allowed `items` for `dropdown`). Empty object when the field has no configuration.
            - `value` AIMetadataValue — Extracted value for an AI metadata field on a document.
              - …
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'extraction_pending', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `retry_after` integer, required — Number of seconds the client should wait before retrying this document.
        - `description` string, required — Human-readable explanation of the current extraction state.
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'extraction_failed', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `description` string, required — Human-readable explanation of the failure.
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'extraction_not_started', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `description` string, required — Human-readable explanation of why extraction has not started.
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'not_found', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `description` string, required — Human-readable explanation.
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'access_denied', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `description` string, required — Human-readable explanation.
      - object — Fields common to every per-document outcome in a batch AI metadata response.
        - `document_id` string, required — The document this result corresponds to. Echoed from the request.
        - `status` 'internal_error', required — Per-document outcome discriminator. Mirrors the HTTP semantics of the single-document endpoint — see the operation description for the mapping. `internal_error` is exclusive to the batch endpoint and indicates an isolated server-side failure for that document only; the request as a whole succeeded and other documents in the same batch are unaffected.
        - `description` string, required — Human-readable explanation.

## Other responses

- `400` — Bad Request error
- `401` — Authentication error
- `403` — Permission error
- `429` — Too many requests error

---

[API](https://skmtc.net/pandadoc/apis/pandadoc-public-api.md) · [All operations](https://skmtc.net/pandadoc/apis/pandadoc-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pandadoc/pandadoc-public-api/versions/0c2b70be3fb0/schema)