Output location and file structure
When a job reaches SUCCEEDED, Amazon Textract Insights has written all of its
output beneath the S3 prefix you supplied in OutputConfiguration.S3Uri. The
entry point is a single job_metadata.json file that points to every result the
job produced. This page describes the layout and how to locate results.
Finding the output
The OutputConfiguration.S3Uri you pass to
StartDocumentInsights is a prefix. The job writes its output under a
job-ID subpath, and GetDocumentInsights returns the path to the job's
metadata file on success:
s3://<bucket>/<prefix>/<job-id>/job_metadata.json
For example, with output prefix
s3://amzn-s3-demo-destination-bucket/results, a successful response
reports:
s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/job_metadata.json
Always start from job_metadata.json. It lists the exact S3 path of every
result.json the job produced, so you do not have to guess paths.
S3 layout
A job writes the following structure beneath
<prefix>/<job-id>/:
<prefix>/<job-id>/job_metadata.json
<prefix>/<job-id>/0/extraction/<n>/result.json # extraction results, one per (split) document n
<prefix>/<job-id>/0/extraction/<n>/result.md|.html|.txt # when OutputFormat.AdditionalFileFormat is ENABLED
<prefix>/<job-id>/0/extraction/<n>/assets/<uuid>.csv # one CSV per table, when CSV text format is requested
<prefix>/<job-id>/0/extraction/<n>/assets/rectified_image_<page>.jpg
<prefix>/<job-id>/0/extraction/<n>/redacted/result.json # when DetectionMode is DETECTION_AND_REDACTION
<prefix>/<job-id>/0/custom/<n>/result.json # custom (blueprint) output, one per document n
<prefix>/<job-id>/0/custom/<n>/redacted/result.json # when DetectionMode is DETECTION_AND_REDACTION
Notes on the path components:
-
0is theasset_id— the input file. (A singleStartDocumentInsightscall processes one input document.) -
<n>is the (split) document index. Without splitting there is a single document0. With splitting enabled, each logical document in the packet gets its ownextraction/<n>andcustom/<n>subpath. See Splitting multi-document files. -
extraction/holds extraction results;custom/holds custom extraction results. An extraction-only job has nocustom/folder, and an inline-blueprint job has onlycustom/(noextraction/). -
redacted/result.jsonappears only when redaction is enabled on the project: underextraction/<n>/forEXTRACTION, and undercustom/<n>/forCUSTOM. No other output file has a redacted copy.
job_metadata.json
job_metadata.json is the index into the job's output. It records the
input and, for each document segment, the S3 paths of the extraction and custom
extraction results:
{ "job_id": "abcd1234efgh", "job_status": "PROCESSED", "output_metadata": [ { "asset_id": 0, "asset_input_path": { "s3_bucket": "amzn-s3-demo-bucket", "s3_key": "documents/invoice-bank-statement-packet.pdf" }, "segment_metadata": [ { "extraction_path": "s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/0/extraction/0/result.json", "custom_path": "s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/0/custom/0/result.json", "custom_status": "MATCH" }, { "extraction_path": "s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/0/extraction/1/result.json", "custom_path": "s3://amzn-s3-demo-destination-bucket/results/abcd1234efgh/0/custom/1/result.json", "custom_status": "MATCH" } ] } ] }
Fields
The job_metadata.json file contains the following fields:
Field |
Meaning |
|---|---|
|
The job identifier. |
|
An internal processing marker. Rely on the API
|
|
One entry per input asset. |
|
The input file index ( |
|
The input document's |
|
One entry per (split) document segment. |
|
S3 path of the extraction |
|
S3 path of the custom (blueprint) |
|
The classification outcome for this segment:
|
|
S3 path of the redacted extraction results, present when
redaction is enabled for |
|
S3 path of the redacted custom extraction results, present
when redaction is enabled for |
Rely on the API status, not job_status.
The job_status field inside job_metadata.json is an
internal marker. Use the Status returned by
GetDocumentInsights (IN_PROGRESS, SUCCEEDED,
FAILED) as the source of truth for job completion.
Locating a specific result
To read results after a successful job:
Read
OutputConfiguration.S3UrifromGetDocumentInsightsto get thejob_metadata.jsonpath.Download
job_metadata.json.For each entry in
output_metadata[].segment_metadata[], readextraction_pathfor the extraction results andcustom_pathfor the custom extraction results. If redaction is enabled, readredacted_extraction_pathinstead ofextraction_path, andredacted_custom_pathinstead ofcustom_path, for downstream use.
For the contents of the extraction result, see Extraction results; for custom extraction results, see Custom extraction result.json field reference; for the redacted file, see Detecting and redacting sensitive data.