Skip to main content

Asynchronous Processing API

The Asynchronous Processing API allows you to process more data with a single request than the Processing API. This is possible because the processing results are not returned immediately but are delivered to your object storage after some time. We recommend using Async API for processing larger images when you prefer not to deal with tiled results and when immediate processing results are not crucial.

The Async API allows you to process the data in a similar way as the Processing API; you define the input data, area of interest, and time range in the body of an Async API request, and the data is processed according to your evalscript. When using Async API keep in mind that:

  • The maximum output image size cannot exceed 10,000 pixels in any dimension.
  • Evalscript can be either sent directly in the request or it can be stored in S3 and referenced in an async request (see parameter evalscriptReference in Async API reference for more details). This allows you to use bigger evalscripts.
  • The processing is asynchronous, which means that you do not get results in the response of your request. Instead, they are delivered to your object storage.
  • A copy of each Async API request is also stored in your object storage. After processing completes, this copy is updated with additional details, including cost information.
  • Only a limited number of asynchronous requests can run concurrently per user. The exact limit depends on your account type.
  • Processing time depends on the request size and the current service load. Typically, the first request takes longer, while subsequent requests are faster.
  • When using the Asynchronous Processing API, a multiplication factor of 2/3 is applied to all requests with an area of at least 10,000 px. This means you can process up to 1.5× more data compared to the Processing API for the same amount of Processing Units (PUs). Requests defining an area smaller than 10,000 px are charged at the standard rate (no multiplication factor applied).

Async API Deployments​

DeploymentAPI end-pointRegion
AWS EU (Frankfurt)https://services.sentinel-hub.com/api/v1/async/processeu-central-1
AWS US (Oregon)https://services-uswest2.sentinel-hub.com/api/v1/async/processus-west-2

AWS Bucket Access​

The Async API uses AWS S3 buckets to:

  • read an evalscript from a S3 bucket (this is optional because an evalscript can also be provided directly in a request)
  • write results of processing to an S3 bucket

One bucket or different buckets can be used for these purposes.

AWS configuration​

Bucket Regions​

The buckets to which the results of asynchronous processing are written must be in the same region as the Async API deployment.

Bucket Policy​

The IAM user or IAM role (depending on which of the access methods described below is used) must have permissions to read and/or write to the corresponding S3 bucket.

The bucket from which the evalscript file is read must have GetObject S3 permission listed in its policy. The bucket where the results are stored must additionally have a PutObject permission in its policy.

Example of a valid bucket policy for the IAM user and a bucket that is used for both reading input data and writing results:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Asynchronous processor permissions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<iam-user-arn->"
      },
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": ["arn:aws:s3:::<bucket-name>/*"]
    }
  ]
}

Access your bucket using the assume IAM role flow​

To access the bucket, the recommended option is to provide the ARN of your IAM role that has access to the bucket:

s3 = {
  "url": "s3://<your-bucket>/<path>",
  "iamRoleARN": "<your-IAM-role-ARN>",
}

When creating an IAM role, you have the option to add a layer of security by specifying the externalId parameter. In case you opt for this, make sure you use your SH domain account ID for its value, which you can find in the User settings page in the Dashboard.

If your IAM role is shared among several principals, and you want to distinguish between their activities by setting roleSessionName in the trust policy of each principal to 'sentinelhub'.

Example of a trust policy for IAM role specifying permissions for a user:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::614251495211:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your-SH-domain-account-id>"
        },
        "StringLike": {
          "sts:RoleSessionName": "sentinelhub"
        }
      }
    }
  ]
}

To give an IAM role access to the bucket, you can either add a permission policy to the IAM role or set a bucket policy in a similar way as above, using your IAM role as principal.

To learn how to create a role for an IAM user, check this link.

Access Your Bucket Using accessKey and secretAccessKey​

The other option is to provide accessKey and secretAccessKey pair in your request. To learn how to configure an access key and access key secret on AWS S3, see the Programmatic access section here.

note

Note that IAM user, to which your access key and secret are linked to, must have permissions to read and/or write to the corresponding S3 bucket.

Once you have accessKey and secretAccessKey, you can use them in a s3 object of your request like this:

s3 = {
  "url": "s3://<your-bucket>/<path>",
  "accessKey": "<your-bucket-access-key>",
  "secretAccessKey": "<your-bucket-access-key-secret>",
  "region": "<your-bucket-aws-region>"
}

The above JSON for accessing the S3 bucket can be sent as:

  • (optional) evalscriptReference.s3 to specify the bucket where the evalscript .js file is available,
  • ouput.delivery.s3 to specify the bucket where the results will be stored.

Check Async API reference for more information.

Checking the Status of the Request​

While the request is running, you can get its status (see this example). Once the processing is finished, the request is deleted from our system. If you try to check its status after it has been deleted, you will get a '404 Not Found' response even if the request was processed successfully.

Troubleshooting​

In case anything goes wrong when creating an Async request, we will return an error message immediately. If anything goes wrong once the Async request has been created, we will deliver an "error.json" file with an error message to your object storage (S3).

Last updated on