Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

CreateEnrichmentJob for Scenario Discovery

Prerequisites

A Scenario Discovery workspace and dataset containing video data

CreateEnrichmentJob operates on an existing workspace + dataset. Before you can call it:

Your calling identity needs permission to invoke the enrichment-job APIs, read the target workspace/dataset/time-series resources, and (when the workspace uses a customer managed KMS key) decrypt with that key.

Minimal caller permission policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeEnrichmentJob",
            "Effect": "Allow",
            "Action": [
                "iotsitewise:CreateEnrichmentJob",
                "iotsitewise:DescribeEnrichmentJob",
                "iotsitewise:CancelEnrichmentJob",
                "iotsitewise:ListEnrichmentJobs"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ReadWorkspaceAndDataset",
            "Effect": "Allow",
            "Action": [
                "iotsitewise:DescribeWorkspace",
                "iotsitewise:DescribeDataset",
                "iotsitewise:ListDatasetDataSegments",
                "iotsitewise:ListTimeSeries",
                "iotsitewise:DescribeTimeSeries"
            ],
            "Resource": "*"
        },
        {
            "Sid": "DecryptWorkspaceCMK",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:DescribeKey"
            ],
            "Resource": "arn:aws:kms:us-east-1:123456789012:key/00000000-0000-0000-0000-000000000000",
            "Condition": {
                "StringEquals": {
                    "kms:ViaService": "iotsitewise.us-east-1.amazonaws.com"
                }
            }
        }
    ]
}

Notes:

If your caller is an application role, pair the policy with a trust policy for the workload type that runs the code:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "ec2.amazonaws.com",
                    "ecs-tasks.amazonaws.com",
                    "lambda.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Trim the Service list to only the workload type that actually runs your code.

Aliases

Enrichment is scoped to a single video time series within the dataset. You identify that time series either by its system-assigned timeSeriesId or by its propertyAlias. Aliases are strongly preferred because they're readable, stable, and consistent with the alias conventions used during bulk import.

For a vehicle-mounted camera, the alias follows the same structure used for MP4 imports:

/car_120/front_left_camera/

Specify exactly one of propertyAlias or timeSeriesId in the request — never both. The API returns ValidationException if both are supplied.

Request shape

Required top-level parameters

Optional top-level parameters

EnrichmentJobConfiguration (union — exactly one member)

Currently the only supported member is eventDetection.

EventDetection fields:

EnrichmentTrimSettings

Both startTime and endTime are TimeInNanos structures:

{
    "timeInSeconds": <Unix epoch seconds>,
    "offsetInNanos": <optional 0..999999999>
}

endTime must be strictly greater than startTime, and both must fall within the dataset's data range.

Python helper to compute the seconds/nanos split:

import datetime

def as_time_in_nanos(dt: datetime.datetime) -> dict:
    ts_ns = int(dt.timestamp() * 1_000_000_000)
    return {
        "timeInSeconds": ts_ns // 1_000_000_000,
        "offsetInNanos": ts_ns % 1_000_000_000
    }

Response

{
    "jobId": "string",
    "status": "PENDING | RUNNING | COMPLETED | FAILED | TIMED_OUT | CANCELLED",
    "createdAt": "2026-07-14T17:00:00Z"
}

HTTP status on success: 200 OK. (Unlike CreateBulkImportJob which returns 202, CreateEnrichmentJob returns 200.)

Errors

Example request payload

Save this as enrichment-job-request.json. The workspaceName is passed on the URL path (or through a CLI flag), not in the JSON body.

{
    "jobConfiguration": {
        "eventDetection": {
            "datasetId": "9005f70f-ebb6-4380-b0f8-6ed83ddbea6a",
            "propertyAlias": "/camera/front",
            "trimSettings": {
                "startTime": {
                    "timeInSeconds": 1778275007,
                    "offsetInNanos": 0
                },
                "endTime": {
                    "timeInSeconds": 1778275307,
                    "offsetInNanos": 0
                }
            }
        }
    },
    "clientToken": "c9c1d2b8-2f4b-4d6a-9b83-8b8a9b9d9a0a"
}

Notes:

Amazon CLI

Command (using an input file):

aws iotsitewise create-enrichment-job \
    --region us-east-1 \
    --workspace-name scenario_discovery_car120 \
    --cli-input-json file://enrichment-job-request.json

Equivalent inline form:

aws iotsitewise create-enrichment-job \
    --region us-east-1 \
    --workspace-name ws-1778278606 \
    --job-configuration '{
      "eventDetection": {
        "datasetId": "9005f70f-ebb6-4380-b0f8-6ed83ddbea6a",
        "propertyAlias": "/camera/front",
        "trimSettings": {
          "startTime": {
            "timeInSeconds": 1778275007
          },
          "endTime": {
            "timeInSeconds": 1778275307
          }
        }
      }
    }'

CLI-only flags:

Sample output:

{
    "jobId": "9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6",
    "status": "PENDING",
    "createdAt": "2026-07-14T17:00:00Z"
}

boto3 (Python)

import uuid
import boto3

client = boto3.client("iotsitewise", region_name="us-east-1")

response = client.create_enrichment_job(
    workspaceName="ws-1778278606",
    jobConfiguration={
        "eventDetection": {
            "datasetId": "9005f70f-ebb6-4380-b0f8-6ed83ddbea6a",
            "propertyAlias": "/camera/front",
            "trimSettings": {
                "startTime": {"timeInSeconds": 1778275007, "offsetInNanos": 0},
                "endTime":   {"timeInSeconds": 1778275307, "offsetInNanos": 0},
            },
        },
    },
    clientToken=str(uuid.uuid4()),
)

print(response["jobId"], response["status"], response["createdAt"])

boto3-specific notes:

curl (raw HTTPS)

CreateEnrichmentJob is POST /workspaces/{workspaceName}/enrichment-jobs on the Amazon IoT SiteWise data plane endpoint. Every request must be signed with Amazon Signature Version 4 (SigV4).

Endpoint

https://data.iotsitewise.<region>.amazonaws.com/workspaces/<workspaceName>/enrichment-jobs

HTTP required elements

Recommended: awscurl

awscurl \
    --service iotsitewise \
    --region us-east-1 \
    -X POST \
    -H "Content-Type: application/json" \
    -d @enrichment-job-request.json \
    https://data.iotsitewise.us-east-1.amazonaws.com/workspaces/scenario_discovery_car120/enrichment-jobs

Plain curl — pre-signed request skeleton

curl -v -X POST \
    "https://data.iotsitewise.us-east-1.amazonaws.com/workspaces/scenario_discovery_car120/enrichment-jobs" \
    -H "Host: data.iotsitewise.us-east-1.amazonaws.com" \
    -H "Content-Type: application/json" \
    -H "X-Amz-Date: 20260714T170000Z" \
    -H "X-Amz-Security-Token: <SESSION_TOKEN_IF_TEMP_CREDS>" \
    -H "Authorization: AWS4-HMAC-SHA256 \
Credential=<ACCESS_KEY_ID>/20260714/us-east-1/iotsitewise/aws4_request, \
SignedHeaders=content-type;host;x-amz-date;x-amz-security-token, \
Signature=<COMPUTED_HEX_SIGNATURE>" \
    --data-binary @enrichment-job-request.json

See the Amazon documentation on Signing Amazon API requests for the full SigV4 derivation.

Sample HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "jobId": "9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6",
    "status": "PENDING",
    "createdAt": "2026-07-14T17:00:00Z"
}

Verifying the job

aws iotsitewise describe-enrichment-job \
    --region us-east-1 \
    --workspace-name scenario_discovery_car120 \
    --job-id 9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6

The status progresses: PENDING → RUNNING → one of COMPLETED, FAILED, TIMED_OUT, or CANCELLED.

Cancelling a running job

aws iotsitewise cancel-enrichment-job \
    --region us-east-1 \
    --workspace-name scenario_discovery_car120 \
    --job-id 9a8b7c6d-5e4f-3a2b-1c0d-e1f2a3b4c5d6

CancelEnrichmentJob is idempotent — calling it more than once for the same jobId returns the current status without error, as long as the job is not already in a non-CANCELLED terminal state (COMPLETED, FAILED, TIMED_OUT), in which case it returns ConflictException. Cancelling a RUNNING enrichment job might fail with an exception if data ingestion into the storage service has already begun.