Textract via SDK Best Practices

Q: Should I always request every FeatureType to be safe?

No. Each FeatureType adds to response size and cost - request only TABLES, FORMS, QUERIES, or SIGNATURES when that specific call actually needs them.

Q: How should I handle async job status at scale?

Use NotificationChannel so Textract pushes completion to SNS instead of polling, always page through Get* results with NextToken, and explicitly handle PARTIAL_SUCCESS as distinct from full success.

This is the checklist to run before and after taking a Textract workload to production from the SDK.

Each item is a rule stated positively, with a one-line rationale. Work top to bottom - the groups run from confidence handling and input quality, through request patterns and structured-extraction efficiency, to reliability, human review, and security. Most rules apply whether you call Textract from boto3 or the AWS SDK v3.

How to Use This List

Treat each box as an audit question against your own document pipeline.
The groups run from output tuning and input quality outward to request patterns, cost, reliability, and security.
Revisit the list whenever you add a new document type, move from images to multi-page PDFs, or add A2I review.
Groups C and D apply mainly once you're past the basics and calling structured or async operations regularly.

A - Confidence Handling

Filter every Block on Confidence yourself. Textract has no MinConfidence request parameter like Rekognition does - every block comes back regardless of score, and thresholding is entirely your responsibility.
Set a different threshold per field, not one global number. A total-due amount and a free-text notes field warrant very different confidence bars given the cost of an error in each.
Route below-threshold extractions to review, not a silent default. Discarding or blindly accepting a low-confidence value both hide a problem your pipeline should surface instead.
Re-tune thresholds when your document source changes. A threshold tuned on clean digital-native PDFs will not necessarily hold for phone-camera scans of paper forms.

Apply the threshold as a filtering step immediately after the call, before any downstream logic sees the data.

# --- Python (boto3) ---
import boto3
 
textract = boto3.client("textract")
with open("form.png", "rb") as f:
    response = textract.analyze_document(Document={"Bytes": f.read()}, FeatureTypes=["FORMS"])
 
MIN_CONFIDENCE = 85.0
low_confidence = [
    b for b in response["Blocks"]
    if b["BlockType"] == "KEY_VALUE_SET" and b["Confidence"] < MIN_CONFIDENCE
]
if low_confidence:
    print(f"{len(low_confidence)} fields below threshold - route to review")

// --- TypeScript (AWS SDK v3) ---
import { TextractClient, AnalyzeDocumentCommand } from "@aws-sdk/client-textract";
import { readFileSync } from "node:fs";
 
const textract = new TextractClient({});
const response = await textract.send(new AnalyzeDocumentCommand({
  Document: { Bytes: readFileSync("form.png") },
  FeatureTypes: ["FORMS"],
}));
 
const MIN_CONFIDENCE = 85.0;
const lowConfidence = (response.Blocks ?? []).filter(
  (b) => b.BlockType === "KEY_VALUE_SET" && (b.Confidence ?? 0) < MIN_CONFIDENCE,
);
if (lowConfidence.length) {
  console.log(`${lowConfidence.length} fields below threshold - route to review`);
}

B - Document Quality & Preprocessing

Deskew and crop scanned images before sending them. A rotated or heavily cropped scan produces lower-confidence reads than the same content aligned and framed correctly.
Use sufficient resolution. Low-DPI scans and heavily compressed photos of documents degrade OCR accuracy in ways no downstream threshold can recover.
Split multi-page PDFs correctly instead of guessing at page count. Sending a multi-page file to the synchronous operations fails outright rather than processing only the first page.
Test against your own real document samples, not a single clean example. Production documents vary far more in quality than whatever sample you tested with first.

C - Sync vs Async Request Patterns

Route anything possibly multi-page to the async job pattern from the start. DetectDocumentText/AnalyzeDocument reject multi-page PDFs and TIFFs outright - build for Start*/Get* before it becomes a production incident.
Use S3Object over raw Bytes once documents exceed 5 MB. The Bytes path caps at 5 MB; S3Object raises that ceiling to 10 MB for synchronous calls and is required for all async calls.
Prefer SNS notifications over tight polling for async jobs. NotificationChannel avoids wasted Get* calls and reduces latency versus a fixed poll interval.
Page through every Get result with NextToken.* A long document's Blocks can span many response pages - stopping after the first page silently truncates your data.
Check JobStatus for FAILED and PARTIAL_SUCCESS, not just SUCCEEDED. A loop that only exits on success can hang forever on a failed job, and a partial success needs its own handling.

D - Forms, Tables & Queries Efficiency

Request only the FeatureTypes a given call actually needs. Each of TABLES, FORMS, QUERIES, and SIGNATURES adds to response size and billed cost - don't request all four by default.
Use Queries for a small, known set of answers instead of full FORMS extraction. Asking three targeted questions is usually cheaper and simpler than reconstructing an entire form to find three values.
Cache extraction results keyed by document version or content hash. Re-running analysis on an unchanged document bills again for no new information.
Build one reusable block-graph-walking utility instead of ad hoc parsing per document type. The Id/Relationships traversal is identical across forms, tables, and queries - a shared helper avoids duplicated, drifting logic.

Reuse a single traversal helper across every extraction path rather than special-casing each FeatureType's parsing.

# --- Python (boto3) ---
def resolve_children(block: dict, by_id: dict, relationship_type: str = "CHILD") -> list[dict]:
    """Shared helper: follow a relationship type from any block to its linked blocks."""
    ids = [
        child_id
        for rel in block.get("Relationships", [])
        if rel["Type"] == relationship_type
        for child_id in rel["Ids"]
    ]
    return [by_id[i] for i in ids if i in by_id]
 
# Works identically for KEY -> VALUE ("VALUE"), TABLE -> CELL ("CHILD"), and QUERY -> QUERY_RESULT ("ANSWER").

// --- TypeScript (AWS SDK v3) ---
import type { Block } from "@aws-sdk/client-textract";
 
function resolveChildren(block: Block, byId: Map<string, Block>, relationshipType = "CHILD"): Block[] {
  // Shared helper: follow a relationship type from any block to its linked blocks.
  const ids = (block.Relationships ?? [])
    .filter((rel) => rel.Type === relationshipType)
    .flatMap((rel) => rel.Ids ?? []);
  return ids.map((id) => byId.get(id)).filter((b): b is Block => b !== undefined);
}
 
// Works identically for KEY -> VALUE ("VALUE"), TABLE -> CELL ("CHILD"), and QUERY -> QUERY_RESULT ("ANSWER").

E - Reliability & Error Handling

Reuse one client across calls. A module-scoped client shares connection pooling and resolved credentials, cutting latency and overhead.
Handle throttling with retries, not a hard failure. Textract returns throttling errors under load; configure retries rather than surfacing them straight to users.
Validate document format and page count before calling synchronous operations. Catching an unsupported multi-page PDF in your own code gives a clearer error than the API's rejection does.
Log the request id on failures. Capture the request identifier from the response metadata so AWS support can trace a specific call.
Use ClientRequestToken on async Start calls.* An idempotency token protects against duplicate jobs when a network retry resends a start request.

F - Human Review & Security

Scope A2I activation conditions narrowly. Overly broad conditions send every document to a human, which defeats the purpose of automating extraction in the first place.
Keep sensitive documents off public workforces. Route anything with personal or confidential content to a private or vetted vendor workforce, never Mechanical Turk.
Grant least-privilege IAM for Textract and any referenced S3 buckets. Scope to specific operations and bucket ARNs rather than broad wildcard access.
Verify the NotificationChannel role's trust policy. The IAM role Textract assumes to publish to SNS must explicitly trust the Textract service principal.
Treat extracted document content with the same data-handling controls as any other user content. Textract inputs often include personal or financial information - apply your existing encryption and access controls to both the source document and the extracted output.

FAQs

What's the single most common Textract accuracy mistake?

Assuming Textract filters by confidence for you. It doesn't - every block comes back regardless of score, so a pipeline that never checks Confidence will happily pass through low-quality extractions as if they were certain.

Does Rekognition-style MinConfidence work with Textract?

No. Textract has no equivalent request parameter - filtering on Confidence happens entirely in your own code, after the response comes back.

Why did my multi-page PDF fail on AnalyzeDocument?

The synchronous operations only accept a single page. Anything with more than one page needs StartDocumentAnalysis/GetDocumentAnalysis (or the text-only equivalents) instead.

Should I always request every FeatureType to be safe?

No. Each FeatureType adds to response size and cost - request only TABLES, FORMS, QUERIES, or SIGNATURES when that specific call actually needs them.

Is it safe to auto-approve extractions above my confidence threshold?

For anything low-stakes, generally yes once tuned against your own documents. For anything consequential, pair the threshold with A2I human review for the specific fields that matter most, rather than trusting a single number completely.

How should I handle async job status at scale?

Use NotificationChannel so Textract pushes completion to SNS instead of polling, always page through Get* results with NextToken, and explicitly handle PARTIAL_SUCCESS as distinct from full success.

Should I make a new client per request?

No. Create one client and reuse it across calls so connection pooling and resolved credentials are shared, which lowers latency, especially in long-running services or warm Lambda invocations.

Textract's Structured-Extraction Model - the block graph these confidence and efficiency rules apply to.
Form & Table Extraction - the FeatureTypes efficiency guidance in group D applies directly.
Asynchronous Document Analysis for Multi-Page Files - the request patterns behind group C.
Human Review with Augmented AI (A2I) - the human-review guidance behind group F.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Textract via SDK Best Practices

This is the checklist to run before and after taking a Textract workload to production from the SDK.

How to Use This List

Treat each box as an audit question against your own document pipeline.
The groups run from output tuning and input quality outward to request patterns, cost, reliability, and security.
Revisit the list whenever you add a new document type, move from images to multi-page PDFs, or add A2I review.
Groups C and D apply mainly once you're past the basics and calling structured or async operations regularly.

A - Confidence Handling

Filter every Block on Confidence yourself. Textract has no MinConfidence request parameter like Rekognition does - every block comes back regardless of score, and thresholding is entirely your responsibility.
Set a different threshold per field, not one global number. A total-due amount and a free-text notes field warrant very different confidence bars given the cost of an error in each.
Route below-threshold extractions to review, not a silent default. Discarding or blindly accepting a low-confidence value both hide a problem your pipeline should surface instead.
Re-tune thresholds when your document source changes. A threshold tuned on clean digital-native PDFs will not necessarily hold for phone-camera scans of paper forms.

Apply the threshold as a filtering step immediately after the call, before any downstream logic sees the data.

# --- Python (boto3) ---
import boto3
 
textract = boto3.client("textract")
with open("form.png", "rb") as f:
    response = textract.analyze_document(Document={"Bytes": f.read()}, FeatureTypes=["FORMS"])
 
MIN_CONFIDENCE = 85.0
low_confidence = [
    b for b in response["Blocks"]
    if b["BlockType"] == "KEY_VALUE_SET" and b["Confidence"] < MIN_CONFIDENCE
]
if low_confidence:
    print(f"{len(low_confidence)} fields below threshold - route to review")

// --- TypeScript (AWS SDK v3) ---
import { TextractClient, AnalyzeDocumentCommand } from "@aws-sdk/client-textract";
import { readFileSync } from "node:fs";
 
const textract = new TextractClient({});
const response = await textract.send(new AnalyzeDocumentCommand({
  Document: { Bytes: readFileSync("form.png") },
  FeatureTypes: ["FORMS"],
}));
 
const MIN_CONFIDENCE = 85.0;
const lowConfidence = (response.Blocks ?? []).filter(
  (b) => b.BlockType === "KEY_VALUE_SET" && (b.Confidence ?? 0) < MIN_CONFIDENCE,
);
if (lowConfidence.length) {
  console.log(`${lowConfidence.length} fields below threshold - route to review`);
}

B - Document Quality & Preprocessing

Deskew and crop scanned images before sending them. A rotated or heavily cropped scan produces lower-confidence reads than the same content aligned and framed correctly.
Use sufficient resolution. Low-DPI scans and heavily compressed photos of documents degrade OCR accuracy in ways no downstream threshold can recover.
Split multi-page PDFs correctly instead of guessing at page count. Sending a multi-page file to the synchronous operations fails outright rather than processing only the first page.
Test against your own real document samples, not a single clean example. Production documents vary far more in quality than whatever sample you tested with first.

C - Sync vs Async Request Patterns

Route anything possibly multi-page to the async job pattern from the start. DetectDocumentText/AnalyzeDocument reject multi-page PDFs and TIFFs outright - build for Start*/Get* before it becomes a production incident.
Use S3Object over raw Bytes once documents exceed 5 MB. The Bytes path caps at 5 MB; S3Object raises that ceiling to 10 MB for synchronous calls and is required for all async calls.
Prefer SNS notifications over tight polling for async jobs. NotificationChannel avoids wasted Get* calls and reduces latency versus a fixed poll interval.
Page through every Get result with NextToken.* A long document's Blocks can span many response pages - stopping after the first page silently truncates your data.
Check JobStatus for FAILED and PARTIAL_SUCCESS, not just SUCCEEDED. A loop that only exits on success can hang forever on a failed job, and a partial success needs its own handling.

D - Forms, Tables & Queries Efficiency

Request only the FeatureTypes a given call actually needs. Each of TABLES, FORMS, QUERIES, and SIGNATURES adds to response size and billed cost - don't request all four by default.
Use Queries for a small, known set of answers instead of full FORMS extraction. Asking three targeted questions is usually cheaper and simpler than reconstructing an entire form to find three values.
Cache extraction results keyed by document version or content hash. Re-running analysis on an unchanged document bills again for no new information.
Build one reusable block-graph-walking utility instead of ad hoc parsing per document type. The Id/Relationships traversal is identical across forms, tables, and queries - a shared helper avoids duplicated, drifting logic.

Reuse a single traversal helper across every extraction path rather than special-casing each FeatureType's parsing.

# --- Python (boto3) ---
def resolve_children(block: dict, by_id: dict, relationship_type: str = "CHILD") -> list[dict]:
    """Shared helper: follow a relationship type from any block to its linked blocks."""
    ids = [
        child_id
        for rel in block.get("Relationships", [])
        if rel["Type"] == relationship_type
        for child_id in rel["Ids"]
    ]
    return [by_id[i] for i in ids if i in by_id]
 
# Works identically for KEY -> VALUE ("VALUE"), TABLE -> CELL ("CHILD"), and QUERY -> QUERY_RESULT ("ANSWER").

// --- TypeScript (AWS SDK v3) ---
import type { Block } from "@aws-sdk/client-textract";
 
function resolveChildren(block: Block, byId: Map<string, Block>, relationshipType = "CHILD"): Block[] {
  // Shared helper: follow a relationship type from any block to its linked blocks.
  const ids = (block.Relationships ?? [])
    .filter((rel) => rel.Type === relationshipType)
    .flatMap((rel) => rel.Ids ?? []);
  return ids.map((id) => byId.get(id)).filter((b): b is Block => b !== undefined);
}
 
// Works identically for KEY -> VALUE ("VALUE"), TABLE -> CELL ("CHILD"), and QUERY -> QUERY_RESULT ("ANSWER").

E - Reliability & Error Handling

Reuse one client across calls. A module-scoped client shares connection pooling and resolved credentials, cutting latency and overhead.
Handle throttling with retries, not a hard failure. Textract returns throttling errors under load; configure retries rather than surfacing them straight to users.
Validate document format and page count before calling synchronous operations. Catching an unsupported multi-page PDF in your own code gives a clearer error than the API's rejection does.
Log the request id on failures. Capture the request identifier from the response metadata so AWS support can trace a specific call.
Use ClientRequestToken on async Start calls.* An idempotency token protects against duplicate jobs when a network retry resends a start request.

F - Human Review & Security

Scope A2I activation conditions narrowly. Overly broad conditions send every document to a human, which defeats the purpose of automating extraction in the first place.
Keep sensitive documents off public workforces. Route anything with personal or confidential content to a private or vetted vendor workforce, never Mechanical Turk.
Grant least-privilege IAM for Textract and any referenced S3 buckets. Scope to specific operations and bucket ARNs rather than broad wildcard access.
Verify the NotificationChannel role's trust policy. The IAM role Textract assumes to publish to SNS must explicitly trust the Textract service principal.
Treat extracted document content with the same data-handling controls as any other user content. Textract inputs often include personal or financial information - apply your existing encryption and access controls to both the source document and the extracted output.

FAQs

What's the single most common Textract accuracy mistake?

Does Rekognition-style MinConfidence work with Textract?

No. Textract has no equivalent request parameter - filtering on Confidence happens entirely in your own code, after the response comes back.

Why did my multi-page PDF fail on AnalyzeDocument?

The synchronous operations only accept a single page. Anything with more than one page needs StartDocumentAnalysis/GetDocumentAnalysis (or the text-only equivalents) instead.

Should I always request every FeatureType to be safe?

No. Each FeatureType adds to response size and cost - request only TABLES, FORMS, QUERIES, or SIGNATURES when that specific call actually needs them.

Is it safe to auto-approve extractions above my confidence threshold?

How should I handle async job status at scale?

Should I make a new client per request?

No. Create one client and reuse it across calls so connection pooling and resolved credentials are shared, which lowers latency, especially in long-running services or warm Lambda invocations.

Textract's Structured-Extraction Model - the block graph these confidence and efficiency rules apply to.
Form & Table Extraction - the FeatureTypes efficiency guidance in group D applies directly.
Asynchronous Document Analysis for Multi-Page Files - the request patterns behind group C.
Human Review with Augmented AI (A2I) - the human-review guidance behind group F.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Textract via SDK Best Practices

Search Documentation

Textract via SDK Best Practices