Before touching APIs or model types, it’s worth placing Comprehend precisely between “a search engine” and “a data scientist who reads text for a living.”

A search engine like Amazon OpenSearch Service is built to answer “which documents contain this word or phrase.” It does not know that a review saying “this laptop is a disaster” is negative, or that “disaster” in that sentence refers to product quality rather than a natural catastrophe. Building that kind of understanding traditionally required a dedicated data science team: collecting labeled training data, choosing and training a model architecture, tuning it, and then maintaining that pipeline forever as language and business needs shift. Amazon Comprehend exists to remove almost all of that specialized labor for a wide range of common NLP tasks, and to make the harder, domain-specific tasks (like recognizing your company’s own product SKUs inside customer messages) achievable by training a custom model on your own labeled examples, without writing a single line of machine learning code.

AWS launched Comprehend in 2017 as part of a wave of managed AI services (alongside Rekognition for images and Transcribe for speech) aimed at making production-grade machine learning consumable through a simple API call rather than a research project. A closely related but separate service, Amazon Comprehend Medical, applies the same underlying approach specifically to clinical text — extracting medications, dosages, and conditions from doctors’ notes — and is covered briefly in the family comparison chapter ahead, since confusing the two is a common early mistake.

It’s worth being precise about the actual business value being unlocked here, because “NLP” can sound abstract until it’s tied to a concrete outcome. A support team that can automatically tag every incoming ticket by sentiment and topic can route the angriest, highest-priority billing complaints to a senior agent within seconds instead of waiting for a human to triage a queue. A compliance team that can automatically flag documents mentioning specific regulated entities can review a fraction of what they used to, focusing only on genuine hits. That shift — from a human reading every document to a human reviewing only what a model has already flagged as interesting — is the entire commercial case for Comprehend, and it’s why the intermediate-level questions in this guide (how fast, how accurate, how much does a wrong answer cost) matter more than the basic question of “what can it detect.”

There’s also a subtler reason Comprehend rewards intermediate-level study specifically: once the first API call works and returns a sentiment label or a list of entities, the interesting problems stop being “how do I call this service” and start being “how confident should I be in this result, what happens when it’s wrong, and how do I teach it something it doesn’t already know.” Those are the questions a data science team would traditionally spend months answering through model evaluation and iteration, and Comprehend compresses that timeline dramatically — but it doesn’t eliminate the need to ask the questions. A team that treats Comprehend as a black box that’s always right, rather than a statistical model with known failure modes, will eventually build a pipeline that confidently automates the wrong decision at scale.

Core Mechanics

You may likeAmazon API Gateway→

2Core Concepts You Must Reason About

Four ideas — confidence scores, document size limits, synchronous versus asynchronous processing, and custom versus built-in models — govern almost every Comprehend design decision.

Every detection Comprehend makes — a sentiment label, a named entity, a custom classification — comes attached to a confidence score between 0 and 1, representing the model’s own estimate of how sure it is. A score of 0.98 on a detected ORGANIZATION entity is a very different signal than a score of 0.52, and mature Comprehend pipelines never treat every detection as equally trustworthy — they set a confidence threshold appropriate to the cost of being wrong, sending low-confidence results to a human reviewer rather than acting on them automatically.

Document size limits shape almost every architecture decision that follows. Real-time synchronous calls accept a single document of up to 5,000 UTF-8 bytes (roughly 5,000 characters of plain English text) per request, or a batch of up to 25 documents in one synchronous call, each under that same size limit. Anything larger — a full contract, a lengthy transcript, a whole customer service call — must either be chunked into smaller pieces before calling the synchronous API, or routed through Comprehend’s asynchronous batch jobs, which read documents directly from an S3 bucket, process them at scale without a per-request size ceiling, and write results back to S3.

This split between synchronous and asynchronous processing is the single biggest architectural fork in any Comprehend design. Synchronous calls return a result in the same HTTP request, seconds after you send it, and are the right fit for real-time use cases like flagging a support message as urgent the moment it arrives. Asynchronous jobs are submitted, run in the background for minutes to hours depending on corpus size, and must be polled or notified for completion — the right fit for processing an entire historical archive of documents, or for tasks like topic modeling and custom model training that are inherently batch operations by nature, not built to run per-request.

Finally, every capability in Comprehend exists in two flavors: built-in (pre-trained) models that AWS trained on broad, general text and that work out of the box with zero setup, and custom models — Custom Classification and Custom Entity Recognition — that you train yourself on your own labeled examples to recognize categories or entities specific to your business, such as internal ticket categories or proprietary product names that a general-purpose model was never taught to recognize.

Within the built-in category, it helps to know the specific vocabulary Comprehend uses so its output reads as structured data rather than a mystery. Entity recognition returns typed results — PERSON, LOCATION, ORGANIZATION, COMMERCIAL_ITEM, EVENT, DATE, QUANTITY, TITLE, and a catch-all OTHER — each with its own confidence score and the exact character offset where it was found in the source text, which matters when you need to highlight or redact that exact span later. Key phrase extraction, by contrast, doesn’t classify anything into types — it simply ranks noun phrases by how central they seem to the document’s meaning, which is why it’s often used for generating quick summaries or search tags rather than for structured data extraction. Syntax analysis, a less commonly used but still built-in capability, tags every token with its part of speech (noun, verb, adjective, and so on), which is mostly useful as a building block for more specialized custom text-processing logic rather than as an end consumer-facing feature on its own.

A working Comprehend system is really three layers: the input source, the Comprehend service boundary itself, and the consumers of its structured output.

Input sources vary by processing mode. For synchronous calls, input is simply the text payload passed directly in the API request — often pulled moments earlier from a database row, a Kinesis stream record, or an incoming API Gateway request body. For asynchronous jobs, input is a manifest of documents already sitting in an S3 bucket, referenced by an input S3 URI when the job is submitted.

The Comprehend service boundary itself is where AWS’s managed, multi-tenant ML infrastructure does the actual work: routing the request to the appropriate pre-trained or custom model, running inference, and packaging the result as structured JSON. For custom models specifically, this boundary also includes a private, versioned model artifact that lives only in your account and is never shared across AWS customers, plus, for real-time custom inference, a provisioned Comprehend endpoint that keeps that custom model warm and ready to serve low-latency requests.

Output consumers are whatever reads the structured result Comprehend returns: application code processing a synchronous JSON response immediately, a Lambda function triggered when an asynchronous job’s output lands in S3, or a downstream analytics pipeline in Athena or QuickSight reading a large batch of job results for trend reporting.

flowchart LR
    subgraph Sources
      A1[Support Tickets / Chat]
      A2[Documents in S3]
      A3[Streaming Text via Kinesis]
    end
    A1 -->|Synchronous API| CMP[Amazon Comprehend]
    A3 -->|Synchronous API| CMP
    A2 -->|Async Batch Job| CMP
    CMP -->|Sentiment / Entities / Key Phrases| RT[Real-Time App Logic]
    CMP -->|Job Output| S3OUT[(S3 Output Bucket)]
    CMP -->|Custom Model Inference| EP[Comprehend Endpoint]
    S3OUT --> ATH[Athena / QuickSight]
    EP --> RT
        

One architectural detail worth internalizing early: Comprehend itself does not permanently store the text you send it for analysis unless you explicitly opt in to allow your inputs to be used for service improvement, or unless you’re running an asynchronous job whose output is written to S3 by design. This “process and forget” default matters a great deal for teams handling sensitive text, since it means the persistence and retention of that text is a decision you make in your own S3 buckets and databases, not one imposed by the NLP layer.

It’s also worth being clear about where the boundary of “Comprehend” actually sits versus where your own application logic begins. Comprehend never decides what to do with a detected entity or sentiment label — it only detects and scores. The decision to route an angry ticket to a senior agent, to redact a detected SSN before storage, or to flag a document for compliance review is business logic you write in the layer consuming Comprehend’s output, typically in the same Lambda function or application service that made the API call in the first place. This separation is deliberate and worth preserving in your own designs: keeping “detection” and “decision” as separate, testable layers makes it far easier to adjust business rules — like tightening a confidence threshold after a false positive incident — without touching anything related to the NLP call itself.

Under The Hood

You may likeAWS Certificate Manager→

4How Comprehend Actually Works Internally

Understanding what happens between submitting text and receiving structured results explains most of Comprehend’s behavior and limitations.

When text arrives at Comprehend, it first passes through tokenization and language detection — breaking the raw string into words and sentence boundaries, and identifying the dominant language, since every downstream model (sentiment, entities, syntax) is language-specific under the hood, even though the API surface looks uniform across languages. This is why language detection is often the very first call made in a Comprehend pipeline handling multilingual input: routing German text through an English sentiment model would silently produce meaningless results rather than an obvious error.

For the built-in capabilities — sentiment, entities, key phrases, syntax — Comprehend runs the tokenized text through pre-trained deep learning models AWS built and continually improves on large, broad text corpora. These models are multi-tenant: every AWS customer calling the sentiment API is running against the same underlying model, which is precisely why built-in detection requires zero setup but also can’t be taught your company’s specific vocabulary.

Custom models work differently under the hood. When you train a Custom Classifier or Custom Entity Recognizer, Comprehend does not build a model from scratch — it applies transfer learning on top of its own base language understanding, fine-tuning that foundation using the labeled examples you provide. This is why custom model training typically needs far fewer labeled examples than training a language model from zero would require, though accuracy still scales meaningfully with the quantity and quality of your labeled training data, and a poorly labeled or inconsistent training set produces a model that confidently makes the same mistakes a human labeler made.

Once a custom model is trained, using it for real-time inference requires provisioning a dedicated Comprehend endpoint for that model version — a small but important operational step, since an endpoint incurs cost for every hour it’s provisioned regardless of how many inference calls it actually serves, making it important to size endpoint throughput to expected traffic and to delete or scale down endpoints that sit idle.

Training itself is submitted as an asynchronous job, much like batch inference: you point Comprehend at a labeled training dataset in S3 (a CSV mapping text or document references to their correct labels or annotated entity spans), and the service runs the training process in the background, reporting back accuracy metrics — precision, recall, and F1 score per label — once complete. These metrics are not decoration; they are the primary tool for deciding whether a model is ready for production or needs more or better-balanced training data. A classifier reporting high overall accuracy but near-zero recall on one specific category is a common and easy-to-miss warning sign that one category was underrepresented in the training set, and that specific category’s real-world classifications should not be trusted until that imbalance is corrected and the model is retrained.

Tracing one document from arrival to structured output ties the previous two chapters together into a single timeline, split by processing mode.

Notice the branch point at step one: everything before it is identical regardless of mode, but the entire operational character of the system diverges based on whether that document needed an answer in the next two seconds or could wait in a queue for the next scheduled batch run. Designing a Comprehend pipeline well means being honest about which of those two your actual use case needs, rather than defaulting to real-time processing for workloads — like nightly compliance review of an entire document archive — that never needed sub-second latency in the first place. A useful diagnostic question when starting a new pipeline is simply: “if this result arrived five minutes late, would anyone notice or care?” If the honest answer is no, an asynchronous batch design will almost always be simpler to build, cheaper to run, and easier to reason about than forcing the same workload through a synchronous, per-request architecture.

At the intermediate level, choosing the right capability — or the right sibling service entirely — matters as much as calling any single API correctly.

A useful rule of thumb: reach for the built-in capabilities first, always — they cost nothing to set up and often solve 80% of a real business problem with zero training data. Reach for Custom Classification when the categories you care about are specific to your business (support ticket types, internal risk categories) and no general-purpose model could reasonably be expected to know them. Reach for Custom Entity Recognition when the things you need to find are domain-specific proper nouns — internal product SKUs, policy numbers, proprietary chemical names — rather than the general people, places, and organizations the built-in recognizer already handles well. Reach for Topic Modeling only when you have a genuinely large corpus and want to discover unknown themes, not confirm known ones — it’s an exploratory tool, not a classification tool, and it always runs as an asynchronous job since discovering topics across thousands of documents is inherently a batch computation.

It’s also worth clearly separating Comprehend from two adjacent AWS services it’s frequently confused with. Amazon Comprehend Medical is a distinct service purpose-built for clinical text, trained specifically to recognize medications, dosages, medical conditions, and protected health information in doctors’ notes and clinical trial documents — using general Comprehend for medical text will miss most of what actually matters clinically, because the base models were never trained on that vocabulary. Amazon Textract, meanwhile, solves a different problem entirely: extracting raw text and structured data (tables, forms) out of scanned documents and images. A very common real-world pattern chains the two together — Textract pulls text out of a scanned insurance claim PDF, and Comprehend then analyzes that extracted text for entities, sentiment, or custom classification — since neither service can do the other’s job.

Choosing between Custom Classification’s two sub-modes is itself worth understanding at this level. Multi-class classification assigns exactly one label per document — appropriate when categories are mutually exclusive, such as routing a ticket to exactly one department. Multi-label classification allows a document to receive several labels simultaneously — appropriate when a single piece of text can genuinely belong to more than one category at once, such as a product review that’s simultaneously about shipping delays and packaging damage. Picking the wrong mode for your actual label structure is a subtle but consequential mistake: forcing genuinely multi-label data into a multi-class model produces a classifier that must arbitrarily pick just one “true” category per document, discarding real signal the business likely wanted to keep.

Comprehend removes the heaviest lifting of production NLP, but it is not a substitute for understanding what its models can and cannot promise.

Scaling Comprehend is largely about choosing the right processing mode for the right volume, and understanding where throughput ceilings actually live.

Synchronous API calls are subject to transactions-per-second (TPS) quotas per account and Region for each capability — for example, a default quota governs how many sentiment detection calls per second an account can make before requests are throttled. These quotas are soft limits that AWS will raise on request for legitimate production workloads, but a design that assumes unlimited synchronous throughput without checking current quotas is a common source of unpleasant surprises during a traffic spike.

Asynchronous batch jobs scale differently: rather than a per-second call rate, the relevant constraint is overall job throughput — how many documents an async job can process per hour — which scales with document count and average size rather than request frequency. A batch job processing one million short support tickets typically completes in well under an hour, while a job processing the same number of much longer legal documents will naturally take longer, since Comprehend allocates processing capacity proportional to actual text volume, not document count.

Custom model endpoints add a third scaling dimension entirely: inference units (IUs). Each IU provisioned for an endpoint guarantees a certain throughput of real-time custom inference requests, and endpoints can be scaled up by adding more IUs (increasing cost and throughput together) or scaled down during low-traffic periods — but unlike Lambda’s automatic scale-to-zero, a Comprehend custom endpoint with zero traffic still bills for its provisioned IUs until you explicitly stop it, which is why many teams schedule endpoint provisioning around known business hours rather than leaving custom endpoints running continuously for sporadic traffic.

Because synchronous quotas are enforced per account, per Region, per capability, a common intermediate-level mistake is not realizing that sentiment detection and entity recognition each have their own independent throughput ceiling — hitting a quota on one does not affect the other, but a design that assumes a single combined “Comprehend quota” will misdiagnose throttling when it happens. Requesting a quota increase through AWS Service Quotas ahead of a known traffic event, rather than discovering the current limit during an incident, is standard practice for any customer-facing pipeline built around synchronous calls. For workloads with genuinely unpredictable or bursty real-time traffic, adding a client-side queue in front of the Comprehend calls — buffering requests briefly and releasing them at a steady rate — is a simpler and often cheaper fix than repeatedly requesting ever-higher quotas.

As a fully managed service, Comprehend’s infrastructure reliability is AWS’s responsibility — but pipeline-level reliability around it is still yours to design.

Comprehend’s underlying infrastructure runs across multiple Availability Zones within a Region, meaning the service itself is resilient to a single data center failure without any configuration on your part — a synchronous API call or a running asynchronous job is not tied to one physical location that could become a single point of failure.

The reliability gap that remains for you to design around is at the application layer: synchronous calls can be throttled under quota pressure and must be retried with exponential backoff, exactly like any other AWS API; asynchronous jobs can occasionally fail partway through, and production pipelines should always check job status via the appropriate DescribeXXXJob API rather than assuming success, routing failed jobs to a dead-letter path for investigation rather than silently losing that batch of documents.

For custom models specifically, an additional reliability consideration is model versioning. Every time you retrain a custom classifier or entity recognizer, Comprehend creates a new model version rather than overwriting the old one, which means a production endpoint continues serving the previous, known-good version until you deliberately point it at a new one — a safety property worth designing around deliberately, since it lets you validate a newly trained model’s accuracy against a held-out test set before ever routing live traffic to it.

This versioning behavior also gives teams a straightforward rollback path if a newly deployed model underperforms in production despite passing offline validation — a real risk, since a held-out test set drawn from historical data can never perfectly predict how a model handles genuinely new phrasing that appears after deployment. Keeping the previous model version’s endpoint configuration on hand, rather than deleting it immediately after a new version goes live, turns a bad model rollout from an emergency retraining exercise into a simple, fast configuration change back to the known-good version.

Because Comprehend often processes deeply sensitive free-form text — support messages, medical notes, financial documents — its security model deserves particular attention.

Identity and access is governed by IAM policies scoped to specific API actions and, for asynchronous jobs, to specific input and output S3 bucket paths, so a service calling DetectSentiment can be denied any ability to submit a custom model training job or read another team’s job output.

Encryption at rest applies to asynchronous job output written to S3 and to custom model artifacts, both of which can be encrypted using AWS KMS with either an AWS-managed or customer-managed key. Encryption in transit is enforced by default across all Comprehend API calls over HTTPS/TLS. For network isolation, VPC endpoints via AWS PrivateLink let Comprehend calls originate from inside a private VPC without traversing the public internet — a common requirement when the text being analyzed is regulated data such as financial records or protected health information.

A detail worth being explicit about: by default, Comprehend does not use customer input or output data to train or improve its own general-purpose models, and AWS provides account-level settings to control data usage for service improvement explicitly. For regulated workloads, this default, combined with encryption and VPC isolation properly configured, is generally sufficient to support HIPAA, PCI-DSS, and SOC 2 obligations — though as with any AWS service, the underlying compliance status depends entirely on your own configuration, not on the service being “compliant” in the abstract.

Custom model training data deserves its own security consideration, since it often contains real production examples of exactly the sensitive text a pipeline is meant to protect. Best practice is to apply the same redaction, access control, and encryption standards to the training dataset in S3 as to any production data store — a training bucket containing thousands of real, unredacted customer support tickets with names, addresses, and account numbers is a genuine data exposure risk if access to that bucket isn’t as tightly scoped as access to production data itself. Some teams intentionally run PII redaction as a preprocessing step on training data too, accepting a small accuracy trade-off in exchange for meaningfully reducing what sensitive information exists in the model’s training corpus at all.

Comprehend exposes its health through CloudWatch, and a handful of signals matter far more than the rest for an intermediate-level pipeline.

A pattern worth adopting for asynchronous workloads specifically is subscribing to Amazon EventBridge events for job state changes (COMPLETED, FAILED) rather than polling DescribeXXXJob on a timer — this reduces unnecessary API calls and lets a downstream Lambda or Step Functions workflow react to job completion within seconds rather than at the mercy of a polling interval. For custom model endpoints, watching per-endpoint invocation counts and latency alongside overall inference unit utilization helps decide when to scale IUs up ahead of a predictable traffic pattern, such as a marketing campaign expected to drive a surge in customer messages.

CloudTrail plays the same governance role for Comprehend that it does across AWS more broadly: every management-plane call — creating a custom model, submitting a job, starting or stopping an endpoint — is logged with the calling identity and timestamp, which becomes essential during a cost review when nobody remembers who provisioned an endpoint that’s been running idle for weeks, or during a security review when it matters whether a specific custom model was accessed by an unexpected identity.

Comprehend’s real value shows up in how naturally it slots into broader AWS pipelines rather than as a standalone tool.

The most common real-time integration pairs Comprehend with AWS Lambda: a Lambda function triggered by an incoming message — from API Gateway, from an SQS queue, or from a Kinesis Data Stream record — calls Comprehend synchronously and acts on the result within the same invocation, a pattern that scales automatically with traffic and requires no servers to manage.

For large-scale batch processing, AWS Step Functions commonly orchestrates the full asynchronous lifecycle: submitting a Comprehend job, waiting for an EventBridge completion event, then triggering downstream processing of the S3 output — all as a single, observable, retryable workflow rather than a fragile chain of manual scripts. Amazon Connect Contact Lens is a well-known example of this pattern productized by AWS itself: it uses Comprehend-style NLP under the hood to analyze call center transcripts in near real time, surfacing sentiment trends and flagged phrases to supervisors without a customer building any of that pipeline themselves.

A further pattern worth naming explicitly is chaining Amazon Transcribe and Comprehend together for audio-based text analytics: Transcribe converts a call recording or voicemail into text, and Comprehend then analyzes that transcript for sentiment and entities — the same two-service chain used conceptually by Contact Lens, but assembled directly by teams who need more customization than that managed product provides.

Serverless orchestration deserves one more specific mention: teams processing high volumes of asynchronous jobs often find that submitting one enormous job for an entire day’s documents is less resilient than submitting several smaller jobs in parallel, since a single job failure partway through means reprocessing everything from the start, while several smaller jobs mean only the failed slice needs to be resubmitted. Step Functions’ native support for parallel branches and per-branch retry policies makes this pattern straightforward to build without custom orchestration code, and it’s a design choice worth making deliberately rather than defaulting to the largest single job size Comprehend will accept.

A few recurring shapes show up again and again in Comprehend-based systems — some worth copying, some worth avoiding.

The confidence-gated automation pattern is Comprehend’s most common production shape: high-confidence detections trigger automated action directly, while low-confidence detections route to a human review queue instead of being silently trusted or silently dropped. The redact-before-store pattern uses PII detection as a mandatory pre-processing gate, stripping sensitive identifiers out of text before it’s ever written to a long-lived data store, reducing the sensitivity — and therefore the compliance burden — of everything downstream.

Most Comprehend production issues trace back to one of a small set of recurring, avoidable mistakes.

Two further habits separate teams that run Comprehend smoothly for years from those that get surprised repeatedly. The first is periodically re-evaluating custom model accuracy against fresh, real production data rather than assuming a model trained a year ago still reflects how customers write today — language, slang, and business terminology drift over time, and a classifier’s accuracy can quietly degrade without anyone noticing until customer complaints reveal it. The second is building confidence-score dashboards, not just accuracy dashboards, since watching the distribution of confidence scores over time can reveal a model gradually becoming less certain about new data well before its actual error rate becomes visible in downstream metrics.

A third habit worth naming is documenting the actual business decision behind every confidence threshold chosen, rather than leaving it as an unexplained magic number in code. A threshold of 0.85 for auto-routing a support ticket by sentiment should have a written rationale — perhaps “at this threshold, false positive rate on a validation set was under 2%, which the support team judged an acceptable trade-off against faster routing” — because thresholds inevitably get revisited after an incident, and a future engineer without that context is likely to either loosen a threshold that was deliberately conservative or tighten one that was deliberately generous, undoing a decision made for good reasons nobody wrote down.

Seeing how NLP shows up in production systems makes the abstract capabilities concrete.