List Extractions

GET /v1/extractions

List extraction records for the authenticated user. Results are returned in reverse chronological order (newest first). Supports cursor-based pagination and filtering by template, batch run, or date range.

Try it

Test this endpoint interactively in the Swagger UI.

Authorization required

Include your API key in the Authorization header.

Request

Headers

Header	Value	Required
`Authorization`	`Bearer <token>`	Yes

Query Parameters

Param	Type	Required	Description
`templateId`	`string`	No	Filter results to extractions from a specific template.
`runId`	`string`	No	Filter results to extractions from a specific batch run. Returns all matching results (ignores `limit`/`cursor`).
`limit`	`number`	No	Maximum number of results to return. Default: `50`, maximum: `100`.
`cursor`	`string`	No	Pagination cursor. Pass the `createdAt` value of the last item from the previous page to fetch the next page.
`dateFrom`	`string`	No	Filter to extractions created on or after this date (`YYYY-MM-DD`).
`dateTo`	`string`	No	Filter to extractions created on or before this date (`YYYY-MM-DD`).

Pagination

The response includes a hasMore boolean. When true, pass the createdAt value of the last item as the cursor parameter to fetch the next page.

When filtering by runId, all matching extractions are returned in a single response (no pagination needed since batch runs are typically small).

Code Examples

curlTypeScriptPython

bash

# List all extractions (default limit of 50)
curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by template and limit results
curl "https://api.docmap.io/v1/extractions?templateId=48291&limit=10" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by batch run ID
curl "https://api.docmap.io/v1/extractions?runId=b4704c6e-8917-4671-8c92-178aec3eba92" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Filter by date range
curl "https://api.docmap.io/v1/extractions?dateFrom=2025-01-01&dateTo=2025-01-31" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

# Paginate through results
curl "https://api.docmap.io/v1/extractions?limit=10&cursor=2025-01-15T09:30:00.000Z" \
  -H "Authorization: Bearer dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"

typescript

const apiKey = process.env.DOCMAP_API_KEY

// List all extractions
const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
})

const { data, hasMore } = await response.json()
console.log(`Found ${data.length} extractions, hasMore: ${hasMore}`)

// Paginate through all results
let cursor: string | undefined
const allExtractions = []

do {
  const url = new URL('https://api.docmap.io/v1/extractions')
  url.searchParams.set('limit', '50')
  if (cursor) url.searchParams.set('cursor', cursor)

  const res = await fetch(url, {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  })
  const page = await res.json()

  allExtractions.push(...page.data)
  cursor = page.hasMore ? page.data.at(-1)?.createdAt : undefined
} while (cursor)

console.log(`Total: ${allExtractions.length} extractions`)

// Filter by template
const filtered = await fetch(
  'https://api.docmap.io/v1/extractions?templateId=48291&limit=10',
  { headers: { 'Authorization': `Bearer ${apiKey}` } },
)

const { data: filteredData } = await filtered.json()

python

import requests

api_key = "dm_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0"
headers = {"Authorization": f"Bearer {api_key}"}

# List all extractions
response = requests.get(
    "https://api.docmap.io/v1/extractions",
    headers=headers,
)
result = response.json()
print(f"Found {len(result['data'])} extractions, hasMore: {result['hasMore']}")

# Paginate through all results
all_extractions = []
cursor = None

while True:
    params = {"limit": 50}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://api.docmap.io/v1/extractions",
        headers=headers,
        params=params,
    )
    page = response.json()

    all_extractions.extend(page["data"])

    if not page["hasMore"]:
        break
    cursor = page["data"][-1]["createdAt"]

print(f"Total: {len(all_extractions)} extractions")

# Filter by date range
response = requests.get(
    "https://api.docmap.io/v1/extractions",
    headers=headers,
    params={"dateFrom": "2025-01-01", "dateTo": "2025-01-31"},
)

Response

Status: 200 OK

The response body contains a data array of extraction records and a hasMore boolean indicating whether additional pages exist.

Top-level Fields

Field	Type	Description
`data`	`ExtractionRecord[]`	Array of extraction records.
`hasMore`	`boolean`	`true` if there are more results beyond the current page. `false` when filtering by `runId` (all results returned).

Extraction Record Fields

Each extraction record in the array contains the same fields as the Run Extraction response:

Field	Type	Description
`id`	`string`	Unique extraction ID (prefixed with `extract-`).
`userId`	`string`	ID of the user who owns this extraction.
`templateId`	`string`	ID of the template used for extraction.
`templateName`	`string`	Display name of the template used.
`fileName`	`string`	Original file name of the uploaded document.
`status`	`"processing"` \| `"completed"` \| `"failed"`	Current extraction status. `"processing"` if still being processed, `"completed"` on success, `"failed"` on error.
`extractedData`	`object` \| `null`	Extracted data matching the template fields. `null` if extraction failed.
`error`	`string` \| `null`	Error message describing the failure. `null` if extraction succeeded.
`variables`	`Variable[]`	Array of template variable definitions used during extraction.
`source`	`"dashboard"` \| `"api"`	How the extraction was triggered.
`runId`	`string` \| `null`	Batch run ID, if one was provided.
`processingTimeMs`	`number` \| `null`	Total processing duration in milliseconds.
`createdAt`	`string`	ISO 8601 timestamp of when the extraction was created.

Example

json

{
  "data": [
    {
      "id": "extract-KmL9nOpQrStUvWxYz",
      "userId": "L5kM9nRpQ7vX3yZ1wD4eF6gHjA2",
      "templateId": "48291",
      "templateName": "Invoice Template",
      "fileName": "invoice-2024-001.pdf",
      "status": "completed",
      "extractedData": {
        "vendor_name": "Acme Corp",
        "invoice_number": "INV-2024-001",
        "total_amount": 1250.00
      },
      "error": null,
      "variables": [
        {
          "name": "vendor_name",
          "type": "string",
          "description": "Name of the vendor or supplier"
        }
      ],
      "source": "api",
      "runId": null,
      "processingTimeMs": 3842,
      "createdAt": "2025-01-20T14:30:00.000Z"
    },
    {
      "id": "extract-Rj4Y8mBpCdEfGhIk",
      "userId": "L5kM9nRpQ7vX3yZ1wD4eF6gHjA2",
      "templateId": "48291",
      "templateName": "Invoice Template",
      "fileName": "invoice-2024-002.pdf",
      "status": "completed",
      "extractedData": {
        "vendor_name": "Global Supplies Ltd",
        "invoice_number": "INV-2024-002",
        "total_amount": 875.50
      },
      "error": null,
      "variables": [
        {
          "name": "vendor_name",
          "type": "string",
          "description": "Name of the vendor or supplier"
        }
      ],
      "source": "dashboard",
      "runId": null,
      "processingTimeMs": 2916,
      "createdAt": "2025-01-19T09:15:00.000Z"
    }
  ],
  "hasMore": true
}

Errors

Status	Code	Description
`401`	`UNAUTHORIZED`	Missing, invalid, or expired API key / token.

List Extractions ​

Request ​

Headers ​

Query Parameters ​

Code Examples ​

Response ​

Top-level Fields ​

Extraction Record Fields ​

Example ​

Errors ​