Skip to main content
POST
/
extractions
Extract Tables from PDF
curl --request POST \
  --url https://api.gonitro.dev/extractions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form method=extract-tables \
  --form 'file=<string>' \
  --form file.0='@example-file'
{
  "result": {
    "tables": [
      {
        "ID": "<string>",
        "pageIndices": [
          123
        ],
        "tableData": {
          "title": "<string>",
          "cells": [
            [
              "<string>"
            ]
          ],
          "footers": [
            "<string>"
          ],
          "confidences": [
            [
              0.5
            ]
          ],
          "averageConfidence": 0.5,
          "headerCells": [
            [
              123
            ]
          ],
          "summaryCells": [
            [
              123
            ]
          ]
        }
      }
    ]
  }
}
The Extract Tables method of the Extractions endpoint allows you to retrieve tabular data from PDF documents. This endpoint requires no additional parameters and automatically identifies all tables present in the file. The endpoint returns an array of tables, each containing the following fields:
  • title: The title of the table (if detected).
  • cells: A 2D array of string values. Indexed as cells[row][column].
  • footers: An array of table footer notes or annotations (if available).
  • confidences: Confidence scores (0 to 1) for each extracted value in the cells array.
  • averageConfidence: The mean confidence score for all cell values within the table.
  • headerCells: Coordinates of detected header cells, provided as [[row, column], ...].
  • summaryCells: Coordinates of summary cells, provided as [[row, column], ...].

​
Uniform Grid

To ensure a consistent and predictable output format, the Extract Tables method processes tables using a uniform grid of cells.

Original PDF

In this example, some cells like “Sign” and “Platform” are composed of multiple cells, due to the fact that the third column (index 2) has multiple row values.

Uniform Grid Division

When processing the original file, the extract tables method will divide the grid in uniform cells, respecting the smallest possible unit, like in the following visualization.

​
Handling Merged Cells

When a table in a PDF contains merged cells, the content is mapped to the cells array based on their position within the uniform grid. Vertical Overlap (Rows) When a cell merges multiple rows, the remaining indices covered by the original merge are returned as empty placeholders ("") in separate rows, to maintain the grid’s structural integrity. You can see it in the cells field in the example below:

Merged rows PDF

Exported rows

Horizontal Overlap (Columns) If a table has cells that overlap over multiple columns, the content will be divided according to the position on the base grid as well. In the following example, the “API Module and Submodule” content in the merged first row is divided in two cells in the response.

Original PDF

In this example, the first row’s content spans two columns.

Uniform Grid Division

When processing the original file, the extract tables method will divide the grid in uniform cells, dividing the content over multiple cells.

​
Output File Format

The endpoint can return output either as JSON or as a binary file. The format depends on the Accept header (details below), which defaults to application/json.

​
Processing

When requesting JSON, you can run the operation synchronously or asynchronously. This is determined by the Prefer header (details below).
  • In sync mode, the response includes a URL pointing to the processed file.
  • In async mode, the request creates a Job, and the response contains the Job ID and status so you can track progress.
Binary (octet-stream) responses are only available for synchronous operations.

​
Custom File Delivery

The endpoint supports custom file-delivery destinations through the optional delivery parameter. You can provide an upload target, such as your own PUT endpoint or a pre-signed S3 URL, and Nitro will upload the resulting file there. This works for both synchronous and asynchronous processing.

  • ​
    Sync delivery

    In synchronous calls, the delivery parameter lets you direct Nitro to upload the output file to a custom URL endpoint or a pre-signed URL (e.g S3), by providing an upload url in the uploadResultTo or uploadResultsTo properties.

    ​
    Custom endpoint

    If implementing the upload endpoint by yourself, make sure your code or middleware configuration accepts requests without content-type headers.

    ​
    S3 delivery

    If you are using S3 to manage delivery uploads, follow this AWS documentation to generate a pre-signed PUT URL.
    If using the AWS provided Python script, omit the Content-Type in Params to get the pre-signed url. For example:
     
        url = generate_presigned_url(
        s3_client,
        "put_object",
        { 
            "Bucket": args.bucket, 
            "Key": args.key,
            # Content-Type: "application/octet-stream" => Omit!
        },
    1000)

  • ​
    Async delivery

    In asynchronous flows, you can also provide a custom URL or pre-signed S3 object via uploadResultTo or uploadResultsTo, to upload your file(s) once the Job is done processing.

    ​
    Callback

    For asynchronous processing, you can also include a callback URL within the delivery parameter. This callback is a POST endpoint that Nitro will call once the Job is created and running, providing details about the file-processing job. Example of Nitro’s callback request body: 
    {
    "jobID": "babe2aa7-9b5d-4eb2-a679-5fc12cf0a490",
    "location": "https://api.gonitro.dev/jobs/babe2aa7-9b5d-4eb2-a679-5fc12cf0a490"
}

​
Response behavior Matrix

This matrix shows the expected response behavior based on content type, sync/async mode, and custom file-delivery settings.
JSON (application/json)Binary (application/octet-stream)
SynchronousReturns a JSON object with a file(s) URL(s).Returns the processed file directly as binary.
Asynchronous (respond-async)Returns a JSON object with a Job ID and status.Async preference ignored, returns sync binary.
Synchronous deliveryFile delivered to custom endpoint / Bucket, returns success confirmation.N/A
Asynchronous deliveryReturns a JSON object with a Job ID and status. The file(s) will be uploaded to the provided PUT endpoint / S3 Bucket at the end of process. If callback url is provided, Nitro will notify the endpoint with a JOB ID and location.N/A

​
Limits

The Platform API has the following limits:
  • File size: Maximum of 25 MB per request. This applies to single-file and multi-file requests.
  • Page count: Maximum of 250 pages per individual document. This applies to single-file and multi-file requests. Multiple documents may exceed 250 pages in total.
  • Retention time: Inputs and outputs are deleted approximately 15 minutes after the operation completes.

​
Request

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Accept
enum<string>
default:*/*

Controls response format and behavior. See endpoint description above for detailed response combinations.

  • application/json: Returns JSON response with operation result
  • application/octet-stream: Returns binary file content
  • */*: Defaults to JSON response
Available options:
application/json,
application/octet-stream,
*/*
​
Prefer
enum<string>

Controls synchronous vs asynchronous operation. See endpoint description above for behavior details.

  • respond-async: Makes request asynchronous, returns job status for polling
  • No value: Synchronous response
Available options:
respond-async

Body

multipart/form-data
​
method
enum<string>
default:extract-tables
required

The Extractions' endpoint method: extract-tables

Available options:
extract-tables
​
file
required

The file to process. It can be provided as a binary upload or as a JSON remote file reference.

​
delivery
object

This endpoint lets you supply your own URL to receive the single-file output. The URL may point to a custom API endpoint or a pre-signed S3 URL.

The HTTP method defaults to PUT, but you can change it based on your implementation needs via the verb parameter. You can also provide custom headers, such as authentication headers or any others required by your endpoint.

Response

Returns either JSON or binary output depending on the Accept header (defaults to JSON). JSON responses include a file URL for synchronous tasks or a job status for asynchronous tasks.

​
result
Tables · object
required