[Beta] Get AI Metadata for Multiple Documents

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

document_idsstring[] required

Documents to fetch AI metadata for. Each entry must be a valid document identifier. Duplicates are not allowed.

field_keysstring[]

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.

Example request

{
  "document_ids": [
    "BhVzRcxH9Z2LgfPPGXFUBa"
  ],
  "field_keys": [
    "Contract value"
  ]
}

Response

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.

countinteger required

Number of entries in results. Equal to the number of document_ids in the request.

Example response

{
  "count": 6,
  "results": [
    {
      "document_id": "BhVzRcxH9Z2LgfPPGXFUBa",
      "status": "ok",
      "ai_metadata": {
        "count": 12,
        "results": [
          {
            "id": "3SBkwkGBbMn6btzHTiKkGn",
            "key": "Counterparty name",
            "value": {
              "value": "Acme Corp"
            }
          }
        ]
      }
    }
  ]
}

v1