Batch vs Real-Time Comprehend Jobs

Q: How do I know when a batch job is done?

Poll Describe*Job (matching the job type) with the JobId and read JobStatus. It moves through SUBMITTED and IN_PROGRESS to a terminal state: COMPLETED, FAILED, or STOPPED.

Q: What InputFormat options does a batch job support?

ONE_DOC_PER_FILE (each file in the S3 prefix is one document) or ONE_DOC_PER_LINE (each line within files is a separate document) - choose based on how your source data is structured.

Q: Can I stop a batch job partway through?

Yes, with the matching Stop*Job operation (for example StopSentimentDetectionJob). The job's JobStatus then reports STOPPED rather than COMPLETED.

Every Comprehend capability comes in two calling shapes. A synchronous Detect* call takes one string and returns a result in under a second. An asynchronous Start*Job call takes an S3 prefix full of documents, processes all of them, and writes results to another S3 prefix - taking minutes, not milliseconds.

Neither shape is "better" in general - they trade off latency, cost, and IAM setup differently, and picking wrong shows up as either an unnecessarily slow loop of synchronous calls or an over-engineered batch pipeline for something that needed one quick answer. This page lays out the decision and the job lifecycle.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
job = comprehend.start_entities_detection_job(
    InputDataConfig={"S3Uri": "s3://my-bucket/docs/", "InputFormat": "ONE_DOC_PER_FILE"},
    OutputDataConfig={"S3Uri": "s3://my-bucket/docs-out/"},
    DataAccessRoleArn="arn:aws:iam::123456789012:role/ComprehendJobRole",
    LanguageCode="en",
)
print(job["JobId"])

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, StartEntitiesDetectionJobCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const job = await comprehend.send(new StartEntitiesDetectionJobCommand({
  InputDataConfig: { S3Uri: "s3://my-bucket/docs/", InputFormat: "ONE_DOC_PER_FILE" },
  OutputDataConfig: { S3Uri: "s3://my-bucket/docs-out/" },
  DataAccessRoleArn: "arn:aws:iam::123456789012:role/ComprehendJobRole",
  LanguageCode: "en",
}));
console.log(job.JobId);

When to reach for this:

Processing an existing archive or nightly export of many documents at once.
Any workload where nothing is waiting on an immediate response.
Cutting cost on custom models by avoiding a continuously billed real-time endpoint.
Reprocessing an entire corpus after retraining a custom model or fixing a bug.

Working Example

Start a batch sentiment job, then poll it until it finishes - the pattern every Start*Job operation shares.

# --- Python (boto3) ---
import boto3
import time
 
comprehend = boto3.client("comprehend")
 
job = comprehend.start_sentiment_detection_job(
    InputDataConfig={"S3Uri": "s3://my-bucket/reviews/", "InputFormat": "ONE_DOC_PER_LINE"},
    OutputDataConfig={"S3Uri": "s3://my-bucket/reviews-out/"},
    DataAccessRoleArn="arn:aws:iam::123456789012:role/ComprehendJobRole",
    LanguageCode="en",
)
job_id = job["JobId"]
 
while True:
    desc = comprehend.describe_sentiment_detection_job(JobId=job_id)
    status = desc["SentimentDetectionJobProperties"]["JobStatus"]
    print("status:", status)
    if status in ("COMPLETED", "FAILED", "STOPPED"):
        break
    time.sleep(30)
 
if status == "COMPLETED":
    output_uri = desc["SentimentDetectionJobProperties"]["OutputDataConfig"]["S3Uri"]
    print("results at:", output_uri)

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, StartSentimentDetectionJobCommand, DescribeSentimentDetectionJobCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
 
const job = await comprehend.send(new StartSentimentDetectionJobCommand({
  InputDataConfig: { S3Uri: "s3://my-bucket/reviews/", InputFormat: "ONE_DOC_PER_LINE" },
  OutputDataConfig: { S3Uri: "s3://my-bucket/reviews-out/" },
  DataAccessRoleArn: "arn:aws:iam::123456789012:role/ComprehendJobRole",
  LanguageCode: "en",
}));
const jobId = job.JobId!;
 
let status = "SUBMITTED";
let outputUri: string | undefined;
while (!["COMPLETED", "FAILED", "STOPPED"].includes(status)) {
  await new Promise((r) => setTimeout(r, 30_000));
  const desc = await comprehend.send(new DescribeSentimentDetectionJobCommand({ JobId: jobId }));
  status = desc.SentimentDetectionJobProperties!.JobStatus!;
  outputUri = desc.SentimentDetectionJobProperties!.OutputDataConfig?.S3Uri;
  console.log("status:", status);
}
 
if (status === "COMPLETED") console.log("results at:", outputUri);

What this demonstrates:

Start*Job returns immediately with a JobId - the actual work happens after the call returns.
Describe*Job is the only way to know progress; there is no push notification, so polling on an interval is the standard pattern.
JobStatus moves through SUBMITTED -> IN_PROGRESS -> a terminal state (COMPLETED, FAILED, or STOPPED).
The completed job's OutputDataConfig tells you exactly where in S3 to find the results.

Deep Dive

The Shape of a Batch Job

Every Start*Job operation - StartEntitiesDetectionJob, StartKeyPhrasesDetectionJob, StartSentimentDetectionJob, StartPiiEntitiesDetectionJob, StartDominantLanguageDetectionJob, and the custom-model jobs StartDocumentClassificationJob/StartEntitiesDetectionJob with a recognizer ARN - takes the same three core inputs: an InputDataConfig (S3 location plus InputFormat, either ONE_DOC_PER_FILE or ONE_DOC_PER_LINE), an OutputDataConfig (S3 location for results), and a DataAccessRoleArn that Comprehend assumes to read the input and write the output. None of that IAM setup exists for a synchronous Detect* call, which needs only the calling identity's own comprehend:Detect* permission.

Why the IAM Role Exists

A synchronous call is Comprehend acting on data you send it directly in the request. A batch job is Comprehend reaching into your S3 buckets on its own, asynchronously, without you present - so it needs its own permission to do that, scoped by a role you create and trust it to assume. This is the most common setup failure for a first batch job: the role exists, but its trust policy doesn't allow the Comprehend service principal to assume it, or its permissions policy doesn't cover the specific input/output prefixes.

Polling, Not Push

There is no webhook or event that fires when a Comprehend job finishes. You poll Describe*Job (matching the job type you started) on an interval and read JobStatus. Terminal states are COMPLETED, FAILED, and STOPPED (if you called Stop*Job); anything else - SUBMITTED, IN_PROGRESS - means keep waiting. For production pipelines, back this polling loop with a reasonable interval (seconds to a minute, not a tight loop) and a timeout so a stuck job doesn't hang your process indefinitely.

Cost and Latency Trade-offs

Synchronous calls are billed per unit of text per call and return in under a second - ideal for anything a user or another system is actively waiting on. Batch jobs are billed similarly per unit of text processed, but the value is in throughput: one job call, one IAM setup, and Comprehend handles distributing work across your documents, rather than your code looping over thousands of synchronous calls itself. For custom models specifically, batch has an additional advantage: it calls the trained model ARN directly, with no hosted endpoint and therefore no hourly cost between runs - a real-time endpoint bills continuously whether or not it receives traffic.

When the Choice Isn't Obvious

A borderline case is a moderate number of documents (dozens to a few hundred) needed fairly soon but not instantly. Looping synchronous calls works but adds request overhead and client-side error handling for each one; a batch job adds job-management code (start, poll, read output) but only one call to kick it off. As a rule of thumb, reach for batch once you're processing enough documents that a client-side loop starts to feel like reimplementing what Start*Job already does for you.

Gotchas

Expecting Start*Job to return results synchronously - it only returns a JobId; you must poll for completion. Fix: implement a Describe*Job polling loop with a sane interval and timeout.
Missing or misconfigured DataAccessRoleArn trust policy - the job fails immediately if Comprehend can't assume the role. Fix: verify the role's trust policy allows the comprehend.amazonaws.com service principal, and its permissions cover the exact input/output S3 prefixes.
Looping synchronous Detect calls over thousands of documents - this is slow, expensive in request overhead, and reimplements what a batch job already does. Fix: switch to the matching Start*Job once document counts grow past a client-side loop's comfort zone.
Leaving a custom model's real-time endpoint running between infrequent batch-like workloads - it bills hourly regardless of traffic. Fix: use StartDocumentClassificationJob/StartEntitiesDetectionJob against the model ARN instead of standing up an endpoint for bursty or infrequent work.
Polling too aggressively - hammering Describe*Job in a tight loop wastes calls without speeding up the job. Fix: poll on an interval of seconds to a minute, matched to how quickly you actually need to know.
Not handling FAILED or STOPPED as distinct from COMPLETED - some pipelines only check for success and hang or silently drop failures. Fix: branch explicitly on all terminal states and surface failures.

Alternatives

Alternative	Use When	Don't Use When
Synchronous `Detect*` (real-time)	One document, an immediate answer is needed	Many documents where a loop would reimplement batch logic
`Start*Job` (batch, this page)	Many documents from S3, minutes of latency is acceptable	A live system or user is waiting on a result right now
Real-time custom endpoint	Live inference against a custom model with continuous traffic	Bursty or infrequent custom-model inference (batch is cheaper)
Batch job against a custom model	Bulk custom classification/recognition, no live traffic	You need a custom-model answer immediately

FAQs

Does every Detect operation have a batch equivalent?

Yes - entities, key phrases, sentiment, PII, and dominant language each have a matching Start*Job operation that processes an S3 prefix instead of one string.

How do I know when a batch job is done?

Poll Describe*Job (matching the job type) with the JobId and read JobStatus. It moves through SUBMITTED and IN_PROGRESS to a terminal state: COMPLETED, FAILED, or STOPPED.

Why do batch jobs need an IAM role that synchronous calls don't?

A batch job has Comprehend reading and writing your S3 buckets asynchronously on your behalf, so it needs a role it can assume with permission to do that. A synchronous call only needs your own calling identity's permission.

Is batch cheaper than real-time?

Per unit of text, pricing is similar. The savings come from avoiding a continuously billed real-time endpoint for custom models, and from avoiding the overhead of looping many synchronous calls yourself.

What InputFormat options does a batch job support?

ONE_DOC_PER_FILE (each file in the S3 prefix is one document) or ONE_DOC_PER_LINE (each line within files is a separate document) - choose based on how your source data is structured.

Can I stop a batch job partway through?

Yes, with the matching Stop*Job operation (for example StopSentimentDetectionJob). The job's JobStatus then reports STOPPED rather than COMPLETED.

When should I default to batch over real-time?

Whenever nothing is actively waiting on the result and you can tolerate minutes of latency - it's typically the cheaper, simpler default for archives, nightly processing, and infrequent custom-model inference.

Comprehend Basics - starting a first batch job alongside the synchronous examples.
Comprehend's Managed NLP Model Surface - the real-time-vs-batch axis across the whole model surface.
Custom Classification & Custom Entity Recognition - choosing an endpoint vs a batch job for custom models.
PII Detection & Redaction - the async PII job's managed redaction mode.

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

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
job = comprehend.start_entities_detection_job(
    InputDataConfig={"S3Uri": "s3://my-bucket/docs/", "InputFormat": "ONE_DOC_PER_FILE"},
    OutputDataConfig={"S3Uri": "s3://my-bucket/docs-out/"},
    DataAccessRoleArn="arn:aws:iam::123456789012:role/ComprehendJobRole",
    LanguageCode="en",
)
print(job["JobId"])

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, StartEntitiesDetectionJobCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const job = await comprehend.send(new StartEntitiesDetectionJobCommand({
  InputDataConfig: { S3Uri: "s3://my-bucket/docs/", InputFormat: "ONE_DOC_PER_FILE" },
  OutputDataConfig: { S3Uri: "s3://my-bucket/docs-out/" },
  DataAccessRoleArn: "arn:aws:iam::123456789012:role/ComprehendJobRole",
  LanguageCode: "en",
}));
console.log(job.JobId);

When to reach for this:

Processing an existing archive or nightly export of many documents at once.
Any workload where nothing is waiting on an immediate response.
Cutting cost on custom models by avoiding a continuously billed real-time endpoint.
Reprocessing an entire corpus after retraining a custom model or fixing a bug.

Working Example

Start a batch sentiment job, then poll it until it finishes - the pattern every Start*Job operation shares.

# --- Python (boto3) ---
import boto3
import time
 
comprehend = boto3.client("comprehend")
 
job = comprehend.start_sentiment_detection_job(
    InputDataConfig={"S3Uri": "s3://my-bucket/reviews/", "InputFormat": "ONE_DOC_PER_LINE"},
    OutputDataConfig={"S3Uri": "s3://my-bucket/reviews-out/"},
    DataAccessRoleArn="arn:aws:iam::123456789012:role/ComprehendJobRole",
    LanguageCode="en",
)
job_id = job["JobId"]
 
while True:
    desc = comprehend.describe_sentiment_detection_job(JobId=job_id)
    status = desc["SentimentDetectionJobProperties"]["JobStatus"]
    print("status:", status)
    if status in ("COMPLETED", "FAILED", "STOPPED"):
        break
    time.sleep(30)
 
if status == "COMPLETED":
    output_uri = desc["SentimentDetectionJobProperties"]["OutputDataConfig"]["S3Uri"]
    print("results at:", output_uri)

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, StartSentimentDetectionJobCommand, DescribeSentimentDetectionJobCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
 
const job = await comprehend.send(new StartSentimentDetectionJobCommand({
  InputDataConfig: { S3Uri: "s3://my-bucket/reviews/", InputFormat: "ONE_DOC_PER_LINE" },
  OutputDataConfig: { S3Uri: "s3://my-bucket/reviews-out/" },
  DataAccessRoleArn: "arn:aws:iam::123456789012:role/ComprehendJobRole",
  LanguageCode: "en",
}));
const jobId = job.JobId!;
 
let status = "SUBMITTED";
let outputUri: string | undefined;
while (!["COMPLETED", "FAILED", "STOPPED"].includes(status)) {
  await new Promise((r) => setTimeout(r, 30_000));
  const desc = await comprehend.send(new DescribeSentimentDetectionJobCommand({ JobId: jobId }));
  status = desc.SentimentDetectionJobProperties!.JobStatus!;
  outputUri = desc.SentimentDetectionJobProperties!.OutputDataConfig?.S3Uri;
  console.log("status:", status);
}
 
if (status === "COMPLETED") console.log("results at:", outputUri);

What this demonstrates:

Start*Job returns immediately with a JobId - the actual work happens after the call returns.
Describe*Job is the only way to know progress; there is no push notification, so polling on an interval is the standard pattern.
JobStatus moves through SUBMITTED -> IN_PROGRESS -> a terminal state (COMPLETED, FAILED, or STOPPED).
The completed job's OutputDataConfig tells you exactly where in S3 to find the results.

Deep Dive

The Shape of a Batch Job

Why the IAM Role Exists

Polling, Not Push

Cost and Latency Trade-offs

When the Choice Isn't Obvious

Gotchas

Expecting Start*Job to return results synchronously - it only returns a JobId; you must poll for completion. Fix: implement a Describe*Job polling loop with a sane interval and timeout.
Missing or misconfigured DataAccessRoleArn trust policy - the job fails immediately if Comprehend can't assume the role. Fix: verify the role's trust policy allows the comprehend.amazonaws.com service principal, and its permissions cover the exact input/output S3 prefixes.
Looping synchronous Detect calls over thousands of documents - this is slow, expensive in request overhead, and reimplements what a batch job already does. Fix: switch to the matching Start*Job once document counts grow past a client-side loop's comfort zone.
Leaving a custom model's real-time endpoint running between infrequent batch-like workloads - it bills hourly regardless of traffic. Fix: use StartDocumentClassificationJob/StartEntitiesDetectionJob against the model ARN instead of standing up an endpoint for bursty or infrequent work.
Polling too aggressively - hammering Describe*Job in a tight loop wastes calls without speeding up the job. Fix: poll on an interval of seconds to a minute, matched to how quickly you actually need to know.
Not handling FAILED or STOPPED as distinct from COMPLETED - some pipelines only check for success and hang or silently drop failures. Fix: branch explicitly on all terminal states and surface failures.

Alternatives

Alternative	Use When	Don't Use When
Synchronous `Detect*` (real-time)	One document, an immediate answer is needed	Many documents where a loop would reimplement batch logic
`Start*Job` (batch, this page)	Many documents from S3, minutes of latency is acceptable	A live system or user is waiting on a result right now
Real-time custom endpoint	Live inference against a custom model with continuous traffic	Bursty or infrequent custom-model inference (batch is cheaper)
Batch job against a custom model	Bulk custom classification/recognition, no live traffic	You need a custom-model answer immediately

FAQs

Does every Detect operation have a batch equivalent?

Yes - entities, key phrases, sentiment, PII, and dominant language each have a matching Start*Job operation that processes an S3 prefix instead of one string.

How do I know when a batch job is done?

Poll Describe*Job (matching the job type) with the JobId and read JobStatus. It moves through SUBMITTED and IN_PROGRESS to a terminal state: COMPLETED, FAILED, or STOPPED.

Why do batch jobs need an IAM role that synchronous calls don't?

Is batch cheaper than real-time?

What InputFormat options does a batch job support?

ONE_DOC_PER_FILE (each file in the S3 prefix is one document) or ONE_DOC_PER_LINE (each line within files is a separate document) - choose based on how your source data is structured.

Can I stop a batch job partway through?

Yes, with the matching Stop*Job operation (for example StopSentimentDetectionJob). The job's JobStatus then reports STOPPED rather than COMPLETED.

When should I default to batch over real-time?

Comprehend Basics - starting a first batch job alongside the synchronous examples.
Comprehend's Managed NLP Model Surface - the real-time-vs-batch axis across the whole model surface.
Custom Classification & Custom Entity Recognition - choosing an endpoint vs a batch job for custom models.
PII Detection & Redaction - the async PII job's managed redaction mode.

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

Batch vs Real-Time Comprehend Jobs

Search Documentation

Batch vs Real-Time Comprehend Jobs