List Extractions

Endpoint

GET /data/extractions

Retrieve a list of extractions with flexible filtering, sorting, and pagination. Essential for polling review status and managing extraction history.

Authentication

string

required

API key for authentication. Your unique API key.

Query Parameters

Filters

string

Filter by specific document UUID. Most efficient for single-document queries.

?document_id=550e8400-e29b-41d4-a716-446655440000

string

Filter by extraction status.Options: completed, processing, failed, pending

boolean

Filter by review requirement.

?needs_review=true   # Only extractions needing review
?needs_review=false  # Only extractions not needing review

boolean

Filter by review completion status.

?is_reviewed=true    # Only reviewed extractions
?is_reviewed=false   # Not yet reviewed

string

Filter by exact filename match.

?original_filename=invoice-2024-001.pdf

string

Filter by creation timestamp (ISO 8601 format).

?created_after=2024-01-15T00:00:00Z

string

Filter by creation timestamp (ISO 8601 format).

?created_before=2024-01-31T23:59:59Z

string

Filter by organization UUID. Admin-only parameter.

Sorting

string

default:"created_at"

Field to sort by.Options: created_at, updated_at, status, original_filename

string

default:"desc"

Sort direction.Options: asc (ascending), desc (descending)

Pagination

integer

default:"0"

Number of results to skip. Use for pagination.

?skip=20  # Skip first 20 results

integer

default:"100"

Maximum results to return. Range: 1-100.

?limit=50  # Return max 50 results

Response

array

Array of extraction objects matching the query.

integer

Total number of extractions matching the filters (before pagination).

integer

Number of results skipped.

integer

Maximum results returned.

Extraction Object

string

Unique extraction ID (UUID).

string

UUID of the source document.

string

Name of the uploaded file.

string

Processing status: completed, processing, failed, pending.

string

ISO 8601 timestamp of extraction creation.

string

ISO 8601 timestamp of last update.

boolean

Whether extraction requires human review.

boolean

Whether extraction has been reviewed by a human.

string | null

ISO 8601 timestamp of review completion. null if not reviewed.

string | null

UUID of user who performed review. null if not reviewed.

object

Extracted data matching the schema.

object | null

Metadata returned by extraction processing. Batch extractions include batch_id here.

object | null

Corrected data after human review. null if not reviewed. Use this for automation if is_reviewed = true.

object

Confidence scores and review flags. Only present in Advanced/VLM extractions.

Examples

Poll for Review Completion

Check if a specific document has been reviewed:

curl "https://api.documind.cloud/api/v1/data/extractions?document_id=550e8400-e29b-41d4-a716-446655440000&limit=1" \
  -H 'X-API-Key: YOUR_API_KEY'

import requests

response = requests.get(
    "https://api.documind.cloud/api/v1/data/extractions",
    headers={"X-API-Key": API_KEY},
    params={
        "document_id": "550e8400-e29b-41d4-a716-446655440000",
        "limit": 1
    }
)

data = response.json()

if data["items"]:
    extraction = data["items"][0]
    
    if extraction["is_reviewed"]:
        print("✓ Review completed!")
        reviewed_data = extraction["reviewed_results"]
    else:
        print("⏳ Still waiting for review...")

const response = await fetch(
  'https://api.documind.cloud/api/v1/data/extractions?document_id=550e8400-e29b-41d4-a716-446655440000&limit=1',
  {
    headers: {
      'X-API-Key': process.env.API_KEY
    }
  }
);

const data = await response.json();

if (data.items.length > 0) {
  const extraction = data.items[0];
  
  if (extraction.is_reviewed) {
    console.log('✓ Review completed!');
    const reviewedData = extraction.reviewed_results;
  } else {
    console.log('⏳ Still waiting for review...');
  }
}

{
  "items": [
    {
      "id": "extr_abc123",
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "original_filename": "invoice-2024-001.pdf",
      "status": "completed",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z",
      "needs_review": true,
      "is_reviewed": true,
      "reviewed_at": "2024-01-15T10:35:00Z",
      "reviewed_by": "user_xyz789",
      "results": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1250.00
      },
      "reviewed_results": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1275.00
      },
      "needs_review_metadata": {
        "confidence_scores": {
          "invoice_number": 95.2,
          "total_amount": 78.5
        },
        "review_flags": {
          "invoice_number": false,
          "total_amount": true
        }
      }
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 1
}

List Pending Reviews

Get all extractions waiting for review:

cURL

curl "https://api.documind.cloud/api/v1/data/extractions?needs_review=true&is_reviewed=false&sort_by=created_at&sort_order=desc&limit=50" \
  -H 'X-API-Key: YOUR_API_KEY'

Python

response = requests.get(
    "https://api.documind.cloud/api/v1/data/extractions",
    headers={"X-API-Key": API_KEY},
    params={
        "needs_review": True,
        "is_reviewed": False,
        "sort_by": "created_at",
        "sort_order": "desc",
        "limit": 50
    }
)

pending = response.json()
print(f"Pending reviews: {pending['total']}")

for extraction in pending["items"]:
    print(f"- {extraction['original_filename']} ({extraction['created_at']})")

Filter by Date Range

Get extractions from last 24 hours:

Python

from datetime import datetime, timedelta

yesterday = (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z"

response = requests.get(
    "https://api.documind.cloud/api/v1/data/extractions",
    headers={"X-API-Key": API_KEY},
    params={
        "created_after": yesterday,
        "status": "completed",
        "limit": 100
    }
)

recent = response.json()
print(f"Extractions in last 24h: {recent['total']}")

Pagination Example

Iterate through all extractions:

Python

def get_all_extractions(api_key, filters=None):
    """
    Fetch all extractions matching filters, handling pagination.
    """
    all_extractions = []
    skip = 0
    limit = 100
    
    while True:
        params = {
            "skip": skip,
            "limit": limit,
            **(filters or {})
        }
        
        response = requests.get(
            "https://api.documind.cloud/api/v1/data/extractions",
            headers={"X-API-Key": api_key},
            params=params
        )
        
        data = response.json()
        all_extractions.extend(data["items"])
        
        # Check if we've fetched everything
        if len(data["items"]) < limit:
            break
        
        skip += limit
    
    return all_extractions

# Usage
filters = {
    "status": "completed",
    "created_after": "2024-01-01T00:00:00Z"
}

all_completed = get_all_extractions(API_KEY, filters)
print(f"Total completed extractions: {len(all_completed)}")

Common Query Patterns

Pattern 1: Polling for Review

# Query by document_id to check specific extraction
params = {
    "document_id": document_id,
    "limit": 1
}

Pattern 2: List All Pending Reviews

# Get extractions waiting for human review
params = {
    "needs_review": True,
    "is_reviewed": False,
    "sort_by": "created_at",
    "sort_order": "asc"  # Oldest first
}

Pattern 3: Get Completed Reviews

# Get extractions reviewed today
from datetime import datetime

params = {
    "is_reviewed": True,
    "created_after": datetime.utcnow().replace(hour=0, minute=0).isoformat() + "Z"
}

Pattern 4: Failed Extractions

# Find failed extractions for retry
params = {
    "status": "failed",
    "created_after": yesterday,
    "sort_by": "created_at",
    "sort_order": "desc"
}

Pattern 5: Organization-Wide Query (Admin)

# Get all extractions for organization
params = {
    "organization_id": "org_uuid",
    "created_after": "2024-01-01T00:00:00Z",
    "limit": 100
}

Response Codes

200 OK

Successful query, returns paginated results.

400 Bad Request

Invalid query parameters:

{
  "detail": "Invalid sort field: invalid_field"
}

403 Forbidden

Insufficient permissions:

{
  "detail": "You don't have permission to access these extractions"
}

500 Internal Server Error

Server-side error:

{
  "detail": "Failed to retrieve extractions. Please try again later."
}

Best Practices

Use Specific Filters

Filter by document_id when possible for fastest queries:

# ✓ Fast: Direct document lookup
params = {"document_id": doc_id, "limit": 1}

# ✗ Slower: Scan all extractions
params = {"limit": 100}  # Then filter in code

Implement Pagination Properly

Handle large result sets with pagination:

def fetch_page(skip=0, limit=100):
    response = requests.get(url, params={"skip": skip, "limit": limit})
    return response.json()

# Process in batches
skip = 0
while True:
    page = fetch_page(skip=skip)
    process_batch(page["items"])
    
    if len(page["items"]) < limit:
        break
    skip += limit

Cache Results When Appropriate

For dashboard views, cache results briefly:

import time

cache = {}
CACHE_TTL = 30  # seconds

def get_pending_reviews_cached(api_key):
    now = time.time()
    
    if "pending" in cache:
        cached_data, timestamp = cache["pending"]
        if (now - timestamp) < CACHE_TTL:
            return cached_data
    
    # Fetch fresh data
    data = fetch_pending_reviews(api_key)
    cache["pending"] = (data, now)
    return data

Use Appropriate Limits

Choose limits based on use case:

# Polling: Just need one result
params = {"document_id": doc_id, "limit": 1}

# Dashboard: Show recent items
params = {"sort_by": "created_at", "limit": 20}

# Batch export: Process all
params = {"limit": 100}  # Max per page

Next Steps

Get Extraction Details

Retrieve complete extraction data by ID

Polling Pattern

Implement review polling for automation

Update Review

Submit reviewed extraction results

Getting Started

Extraction Workflow

Review Workflow

Data Endpoints

Integration Patterns

Endpoint

Authentication

Query Parameters

Filters

Sorting

Response

Extraction Object

Examples

Poll for Review Completion

List Pending Reviews

Filter by Date Range

Common Query Patterns

Pattern 1: Polling for Review

Pattern 2: List All Pending Reviews

Pattern 3: Get Completed Reviews

Pattern 4: Failed Extractions

Pattern 5: Organization-Wide Query (Admin)

Response Codes

200 OK

400 Bad Request

403 Forbidden

500 Internal Server Error

Best Practices

Next Steps

Get Extraction Details

Polling Pattern

Update Review

​Endpoint

​Authentication

​Query Parameters

​Filters

​Sorting

​Pagination

​Response

​Extraction Object

​Examples

​Poll for Review Completion

​List Pending Reviews

​Filter by Date Range

​Pagination Example

​Common Query Patterns

​Pattern 1: Polling for Review

​Pattern 2: List All Pending Reviews

​Pattern 3: Get Completed Reviews

​Pattern 4: Failed Extractions

​Pattern 5: Organization-Wide Query (Admin)

​Response Codes

​200 OK

​400 Bad Request

​403 Forbidden

​500 Internal Server Error

​Best Practices

​Next Steps

Get Extraction Details

Polling Pattern

Update Review

Endpoint

Authentication

Query Parameters

Filters

Sorting

Pagination

Response

Extraction Object

Examples

Poll for Review Completion

List Pending Reviews

Filter by Date Range

Pagination Example

Common Query Patterns

Pattern 1: Polling for Review

Pattern 2: List All Pending Reviews

Pattern 3: Get Completed Reviews

Pattern 4: Failed Extractions

Pattern 5: Organization-Wide Query (Admin)

Response Codes

200 OK

400 Bad Request

403 Forbidden

500 Internal Server Error

Best Practices

Next Steps