Documents Data (Flat, Bulk)

POST/api/v1/deployments/{deploymentId}/documents/data

Bulk version of Document Data (Flat): pass every file ID you want data for and get one response back — a single document is just a one-element fileIds array. Each entry follows exactly the single-document shape and rules (tables keyed by table slug, rows keyed by column slug, $-prefixed system keys, child tables nested inline).

Parameters

Name	Type	In	Required	Description
`deploymentId`	string	path	Yes	The model or deployment the documents belong to.
`fileIds`	string[]	body	Yes	File IDs to fetch (1–100). Duplicates are ignored.
`include`	string[]	body	No	Optional enrichments: confidence, boundingBoxes, grounding, validations, metadata.

Behavior

documents preserves the order of fileIds (after de-duplication). Each entry carries its own status — COMPLETED entries have data, PROCESSING/FAILED entries have a jobId (and errorMessage on failure) — so a batch with in-flight documents still returns everything else.
File IDs that don't exist or don't belong to the deployment are listed in missing instead of failing the batch.
Slug problems (a table or column without a slug, or a duplicate slug) are schema-level and affect every document identically, so they fail the whole request with 422 — same as the single-document endpoint.
include: ["validations"] adds the per-cell validations array and the document-level validations object — status, failCount, custom checks and rule rules — to each COMPLETED entry, exactly as on the single-document endpoint. See Validations.
include: ["metadata"] adds a top-level _meta block to each documents entry, describing the document rather than its cells. See Metadata.
The response envelope carries modelId and viaDeploymentId beside documents and missing: the model that served the request, and the deployment it arrived through or null when the model was addressed directly.

Request

const response = await fetch(
`https://app.limai.io/api/v1/deployments/${deploymentId}/documents/data`,
{
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fileIds: ["file_9k2mx4", "file_3p7va1"],
    include: ["validations"]
  })
}
)
const { documents, missing } = await response.json()

Response

Response200

{
  "documents": [
    {
      "fileId": "file_9k2mx4",
      "status": "COMPLETED",
      "jobId": "job_5tr8n1",
      "data": {
        "invoices": [
          {
            "$id": "row_h1",
            "$index": "0",
            "invoice_number": {
              "value": "INV-2041"
            },
            "total_amount": {
              "value": "1250.00"
            },
            "line_items": [
              {
                "$id": "row_li1",
                "$index": "0",
                "description": {
                  "value": "Solar panel mounting kit"
                },
                "amount": {
                  "value": "740.00"
                }
              }
            ]
          }
        ]
      }
    },
    {
      "fileId": "file_3p7va1",
      "status": "PROCESSING",
      "jobId": "job_8xw2k9"
    }
  ],
  "missing": [
    "file_gone01"
  ]
}

Response422

{
  "error": "Column \"Invoice Number\" (col_8s3k1) has no slug. Run the slug backfill for this schema."
}

Validations

Validations are resolved per document, so each entry carries its own status and its own rule results. The shapes are the ones documented under Document Data (Flat), and Validations covers what the fields mean.

Response200

{
  "documents": [
    {
      "fileId": "file_9k2mx4",
      "status": "COMPLETED",
      "jobId": "job_5tr8n1",
      "data": {
        "invoices": [
          {
            "$id": "row_h1",
            "$index": "0",
            "total_amount": {
              "value": "1250.00",
              "validations": [
                {
                  "check": "vrule_5f3",
                  "source": "RULE",
                  "passed": false,
                  "message": "Total within approval limit: expected between 0 and 1000, got 1250",
                  "expected": "between 0 and 1000",
                  "actual": "1250",
                  "name": "Total within approval limit",
                  "scope": "FIELD",
                  "operator": "IS_BETWEEN",
                  "amended": false,
                  "previousValue": null,
                  "amendedValue": null
                }
              ]
            }
          }
        ]
      },
      "validations": {
        "status": "failed",
        "failCount": 1,
        "checks": [],
        "rules": [
          {
            "check": "vrule_5f3",
            "name": "Total within approval limit",
            "scope": "FIELD",
            "operator": "IS_BETWEEN",
            "passed": false,
            "message": "Total within approval limit: expected between 0 and 1000, got 1250",
            "failures": [
              {
                "table": "invoices",
                "rowId": "row_h1",
                "column": "total_amount",
                "expected": "between 0 and 1000",
                "actual": "1250"
              }
            ]
          }
        ]
      }
    },
    {
      "fileId": "file_3p7va1",
      "status": "PROCESSING",
      "jobId": "job_8xw2k9"
    }
  ],
  "missing": [
    "file_gone01"
  ]
}

PROCESSING and FAILED entries carry no validations object, and neither do file IDs listed in missing.

Metadata

include: ["metadata"] adds a reserved _meta key to each documents entry, beside fileId, status and data. It describes the document itself, not its cells, so the flat data under data is unchanged.

Response200

{
  "documents": [
    {
      "fileId": "file_9k2mx4",
      "status": "COMPLETED",
      "jobId": "job_5tr8n1",
      "data": {
        "invoices": [
          {
            "$id": "row_h1",
            "$index": "0",
            "invoice_number": {
              "value": "INV-2041"
            }
          }
        ]
      },
      "_meta": {
        "documentId": "cmm3k7r2v0007",
        "fileName": "broker-quote-2026-09.pdf",
        "submittedAt": "2026-09-01T10:12:33.000Z",
        "submittedBy": {
          "id": "usr_8a2f",
          "name": "Jane Doe",
          "email": "jane@acme.com"
        },
        "extractedAt": "2026-09-01T10:14:02.000Z"
      }
    },
    {
      "fileId": "file_3p7va1",
      "status": "PROCESSING",
      "jobId": "job_8xw2k9",
      "_meta": {
        "documentId": "cmm3k1q9x0001",
        "fileName": "invoice_001.pdf",
        "submittedAt": "2026-09-02T08:41:10.000Z",
        "submittedBy": null,
        "extractedAt": null
      }
    }
  ],
  "missing": [
    "file_gone01"
  ]
}

Fields of _meta:

Field	Description
`documentId`	The file's ID.
`fileName`	The uploaded file name.
`submittedAt`	When the file was uploaded, shown as "Date Added" in the grid.
`submittedBy`	The user who uploaded the document, as `{ id, name, email }`. `null` when the uploader is unknown.
`extractedAt`	When the latest extraction run completed. `null` when no run has completed.

_meta is present on every documents entry, whatever its status — PROCESSING and FAILED entries carry it too. File IDs listed in missing have no entry and so no _meta.

An unrecognized include value is rejected with a 400 — {"error": "Validation error", "details": …} — before any document is read.

Backwards compatibility

Without metadata in include, the response shape is exactly the one documented under Response.

Documents Data (Flat, Bulk)

Parameters

Behavior

Request

Response

Validations

Metadata

Backwards compatibility

On this page