Amazon Comprehend's key phrase API finds noun phrases in UTF-8 text. Use it to collect phrases for document tags, search indexes, or later review. It does not write a summary or label a phrase with an entity type such as PERSON or LOCATION.

This guide covers the real-time DetectKeyPhrases call, its batch alternative, and asynchronous jobs for documents in Amazon S3. The limits and language codes below follow the current DetectKeyPhrases API reference and AWS's Comprehend quotas.

How Amazon Comprehend extracts key phrases

A key phrase is a noun phrase, usually a noun with words that modify it. For example, Comprehend may identify “a beautiful day” as one phrase. Results are spans from the text you sent, such as a product name, an organization, or a technical term.

Key phrases and named entities answer different questions

Key phrase detection returns noun phrases. Named entity detection returns text spans with a category such as PERSON, LOCATION, or DATE. “Seattle” could appear in both results, but only entity detection supplies an entity type. Use DetectEntities when you need those predefined labels, or a custom entity model when you need types specific to your domain.

Key parameters for a request

A real-time request supplies two required values:

  • Text: one UTF-8 text string under the single-document size limit.
  • LanguageCode: the language of that text. Comprehend does not detect the language as part of this call.

The input must be non-empty plain text. If the source is HTML, a PDF, or an image, extract the text first and send the text to this API.

Understanding the response

DetectKeyPhrases returns a KeyPhrases array. Each item includes:

  • Text: the phrase Comprehend found.
  • Score: Comprehend's confidence in the detection. AWS describes it as confidence that the text is a noun phrase; it is not a universal measure of business relevance or correctness.
  • BeginOffset and EndOffset: zero-based offsets locating the phrase in the original input. AWS's example locates “today” at offsets 14 and 19. Keep the exact input text if you need to map offsets back to it.

Scores do not prescribe a universal cutoff. Choose a threshold only after checking results against examples from your own documents and the cost of keeping or dropping a phrase.

Example with Boto3

Install Boto3, configure AWS credentials and a default Region, then grant the caller permission to invoke comprehend:DetectKeyPhrases. This example also counts the encoded input bytes; Python's character count alone does not measure the UTF-8 request size.

import boto3

text = "Amazon Comprehend extracts phrases from customer reviews."
utf8_size = len(text.encode("utf-8"))
print(f"Input size: {utf8_size} UTF-8 bytes")

comprehend = boto3.client("comprehend")
response = comprehend.detect_key_phrases(
    Text=text,
    LanguageCode="en",
)

for phrase in response["KeyPhrases"]:
    print(
        f"{phrase['Text']!r}: score={phrase['Score']:.3f}, "
        f"offsets={phrase['BeginOffset']}–{phrase['EndOffset']}"
    )

The request's language code must match the input. The SDK uses the configured credentials and Region; the service rejects unsupported languages, invalid requests, and text over the applicable limit.

Where key phrase extraction fits

Organizing documents

Applications can store extracted phrases as candidate tags or metadata, then let their own rules or reviewers decide which labels to keep. The phrases are useful signals from the text, not a complete classification of the document.

Do key phrases create summaries?

No. The API returns phrases, not a shortened or rewritten account of the source. You can use phrases as one input to a separate summarization or review workflow, but they omit the relationships and context expressed by the full text.

Enriching a search index

Adding selected phrases to a search index can give users another way to find documents. Test the effect on your own queries: phrase extraction does not interpret a user's intent or guarantee better ranking by itself.

Choose the API for your workload

Language and text preparation

Key phrase detection supports these primary language codes: ar, de, en, es, fr, hi, it, ja, ko, pt, zh, and zh-TW. The last two codes mean Chinese (simplified) and Chinese (traditional), respectively. Every document in a batch or asynchronous job must use the one language code supplied for that request. See AWS's current feature-by-feature language list before choosing a code.

Review scores against your use case

Scores help compare detections, but a high score does not guarantee that a phrase is useful for your application. Review a representative sample, define what counts as a useful result, and set any filter based on that evaluation. Do not treat a fixed value such as 0.8 as an AWS recommendation.

UTF-8 input limits and processing options

Measure the UTF-8 encoded input, not the number of characters shown by an editor. AWS documents these limits for the built-in key phrase APIs:

OperationInput limitsWhen to use it
DetectKeyPhrasesOne document, less than 100 KB of UTF-8 encoded text.One real-time request.
BatchDetectKeyPhrasesUp to 25 documents, each no larger than 5 KB of UTF-8 text. All documents share one language code.Several short documents in one real-time request.
StartKeyPhrasesDetectionJobFor each document: up to 1 MB. The job's input files must total at least 500 bytes and can total up to 5 GB. AWS also sets a maximum of 1,000,000 input files when each file is one document, or 1,000,000 input lines when each line is one document.A collection of documents in S3 processed as an asynchronous job. Choose one document per file or one document per line in InputFormat.

These are distinct limits: splitting a long document into multiple entries does not make it a single larger document in the batch API. For a document over the synchronous limit, split it at meaningful boundaries and retain the mapping to each source segment, or use an asynchronous job when the document and corpus fit its limits. Splitting can change context, so inspect the resulting phrases.

The asynchronous job reads UTF-8 input from S3 and writes results to an S3 output location. Review the current job API reference and input format options when setting it up.

Handle invalid requests and batch errors

Fix a rejected request

For a single-document call, verify that the text is non-empty, its UTF-8 size is within the limit, and LanguageCode is supported. The SDK raises an error if the request itself fails.

A batch request can return HTTP 200 and still contain per-document errors. Check both ResultList and ErrorList in the response. Each item's Index points to its position in your input list, so preserve the original list to associate successful phrases or failed documents with their source. Retry only errors your application can recover from; a document that is too large or uses an unsupported language needs correction, not an unchanged retry. See the BatchDetectKeyPhrases response and error fields.

Next steps

Use DetectKeyPhrases for one short text, BatchDetectKeyPhrases for up to 25 short documents, and StartKeyPhrasesDetectionJob for an S3 collection that fits the asynchronous quotas. Keep the original text when offsets matter, validate score filters with your data, and use entity detection when you need typed entity labels.

If you need to recognize domain-specific labels instead of general noun phrases, read our guide to custom entity recognition in Amazon Comprehend.