Create task

POST /tasking/v2/tasks

With a valid contractID, you can task ICEYE’s constellation directly using the createTask operation. See also the Tasking API Specification for an exhaustive list of optional parameters to customize the task.

Required parameters

The required parameters of the tasking createTask operation are specified in the request body of a POST operation.

Point of interest

The center-point over which the image will be acquired. The point of interest should be specified as a valid set of earth-centered coordinates, pointOfInterest[lat] and pointOfInterest[lon] (latitude and longitude), in WGS 84 coordinates.

"pointOfInterest": {
  "lat": -23.700552,
  "lon": 133.882675
},

Acquisition window

A time window with a start and end during which ICEYE’s constellation can acquire the SAR Data.

  • start time cannot be immediate and must be set to a minimum number of hours after the time of the tasking request. For details, see the Min time before collection to choose target table column in section 3.4 Tasking Priority Options of the Data Product Specification document.

  • end cannot be more than 14 days from the time of the tasking request.

  • The acquisition window must be at least 24h wide, end - start >= 24h.

"acquisitionWindow": {
  "start": "2023-12-29T23:20:11.315Z",
  "end": "2023-12-30T01:20:11.315Z"
},

The timestamp format follows RFC 3339. To specify the same UTC time in a +3 hour timezone, users can use:

"acquisitionWindow": {
  "start": "2023-12-30T02:20:11.315+03:00",
  "end": "2023-12-30T04:20:11.315+03:00"
},

Imaging mode

Imaging mode defines how a satellite collects the imaging data, which affects the azimuthal length, swath width, ground resolution, and image quality of the final image.

The imaging modes described in the ICEYE Product Specification are mapped to the string value of the imagingMode parameter as follows:

Product guide image mode API imagingMode

Strip

STRIPMAP

Scan

SCAN

Scan Wide

SCAN_WIDE

Spot

SPOTLIGHT

Spot Extended Area

SPOTLIGHT_EXTENDED_AREA

Spot Fine

SPOTLIGHT_FINE

Dwell

SPOTLIGHT_EXTENDED_DWELL

Dwell Fine

SPOTLIGHT_EXTENDED_DWELL_FINE

Dwell Precise

SPOTLIGHT_EXTENDED_DWELL_PRECISE
The allowed imaging modes vary by contractID.

For example, to specify the imaging mode as a parameter in a request body:

"imagingMode": "SPOTLIGHT",

Optional parameters

Reference

A string that can be used to identify tasks uniquely or group multiple tasks together for easier tracking. The reference parameter accepts UTF-8 characters but it has a limitation of 256 string length.

"reference": "customer task reference 123-456",

Exclusivity

Exclusivity indicates whether the task products should be released to the public catalog or remain within the customer’s private catalog for an agreed period of time (as reflected both in the pricing and the contractual agreement).

Task exclusivity can take one of the following string values:

Exclusivity Description

PUBLIC

The task products are initially private, but are ultimately transferred (anonymously) to the ICEYE public catalog after 7 days.

PRIVATE

The task products remain private for the time period agreed in your contract with ICEYE. After the agreed time period has elapsed, the image products can be transferred (anonymously) to the ICEYE public catalog.
The exclusivity parameter is constrained by the terms of your contract, which could restrict the API operation to allow only one of the options, or allow both options. For example, if you specify PUBLIC and it is not allowed by your contract, the API operation returns the not allowed error.

For example, to specify exclusivity as a parameter in a request body:

"exclusivity": "PRIVATE",

Priority

The task priority specifies the priority level that applies when the scheduler has to resolve a potential conflict. In the case of a conflict, a COMMERCIAL task will always take priority over a BACKGROUND task.

Task priority can take one of the following string values:

Priority Description

BACKGROUND

The task will be scheduled if there are no conflicts, but will be removed from the schedule if a higher priority task is created in the same time window.

COMMERCIAL

The task has a higher priority than BACKGROUND (90% probability of task fulfillment). See also Accuracy of imaging time.

Defaults to the contractually agreed priority from your contract.

For example, to specify the priority as a parameter in a request body:

"priority": "COMMERCIAL",

Service Level Agreement

The service level agreement (SLA) specifies a guaranteed availability time for tasked image products. The availability time is the time elapsed between the moment a satellite finishes acquiring the raw image, and the time when the image products become available for download from ICEYE.

Availability time does not include the time required to download the product data or deliver the data to an external location.

The sla parameter can take one of the following string values:

SLA Description

SLA_8H

Promises availability of standard image products within 8 hours of the satellite acquiring the image (normal delivery priority).

SLA_3H

Promises availability of standard image products within 3 hours of the satellite acquiring the image.

Defaults to SLA_8H.

For example, to specify the SLA as a parameter in a request body:

"sla": "SLA_8H",

EULA

The end user license agreement (EULA) defines the terms of use for purchased SAR products, also defining how widely products can be distributed. For full details of the EULA, see the relevant terms of your contract.

The eula parameter can take one of the following string values:

EULA Description

GOVERNMENT

This EULA option should be selected by a governmental organization that has contracted directly with ICEYE or by a reseller that plans to share products with a governmental organization. Government End Users shall use Products, Derivatives and Documentation solely under Government EULA.

STANDARD

This EULA option should be selected by a commercial organization that has contracted directly with ICEYE or by a reseller that plans to share products with a commercial organization. All other End Users than Government End Users shall use Products, Derivatives and Documentation solely under Standard EULA.

For example, to specify the EULA as a parameter in a request body:

"eula": "STANDARD",

Product types

The productTypes parameter specifies which SAR product types to process in your tasking request. This parameter gives you control over the products generated and delivered. By default, your task will deliver the SLA products as configured in your contract.

"productTypes": ["GRD", "SLC", "QLK"],

See the SLA products table for details on which product types are available for each imaging mode.

Some product types may only be available for specific imaging modes and contract configurations.

Incidence angle

The incidenceAngle parameter specifies the range of incidence angles that are accepted by this task.

"incidenceAngle": {
  "min": 10,
  "max": 45
},

The default incidence angle range is automatically set to the recommended range (Performant Incidence Range) of the specified imaging mode, as documented in the ICEYE Product Specification.

If you specify the incidenceAngle parameter explicitly, we recommend that you choose a range lying within the documented Performant Incidence Range for the specified imaging mode, in order to obtain a high quality image. Angle ranges wider than 10-45 degrees are disallowed, because incidence angles outside this range are not commercially supported in the constellation.

If you task with an incidence angle range that lies outside the Performant Incidence Range for the specified imaging mode, ICEYE does not guarantee the resulting image quality.

Look side

Possible values are ANY, LEFT and RIGHT. Default to ANY.

"lookSide": "ANY",

Pass direction

Possible values are ANY, ASCENDING and DESCENDING. Default to ANY.

"passDirection": "ASCENDING",

Deliveries

You can specify the delivery location for products using the deliveries parameter. The deliveries parameter is an array of delivery objects, defined by the following properties:

  • location — delivery location object, which specifies a delivery location using the following properties:

    • configID — reference to a delivery location config, which was created by the COSP team on behalf of a customer. If you do not have access to a config ID for a delivery location, contact the COSP team for help.

    • path — specifies the delivery location, using the appropriate URL format for the chosen delivery method. This value must match one of the location paths in your contract.

      • For SFTP delivery: You must use the exact path value from your contract’s deliveryLocations array (the entry with method: "sftp"). Call getContract to retrieve this path.

    • subPath (optional) — specifies a subfolder of the delivery location. This value can be freely chosen.

Delivered files are placed directly into the folder specified by path (optionally extended by subpath) — the Delivery API does not create an additional folder to group delivered files together.

AWS S3 Delivery Example

To specify delivery of products to AWS S3, in the folder1/folder2/ subpath of the DOC-EXAMPLE-BUCKET1 bucket:

"deliveries": [
  {
    "locations": [
      {
        "configID": "XXXXXX-XXXXXX-XXXXXX",
        "path": "DOC-EXAMPLE-BUCKET1",
        "subPath": "folder1/folder2/"
      },
      {
        "configID": "XXXXXX-XXXXXX-XXXXXX",
        "path": "DOC-EXAMPLE-BUCKET2",
        "subPath": "folder3/folder4/"
      },
    ]
  },
],

SFTP Delivery Example

To use SFTP delivery, you need to discover both the config ID and the path:

  1. Call the getContract operation to find the SFTP path in the contract’s deliveryLocations.

  2. Call the listDeliveryLocationConfigs operation to discover the SFTP config ID (look for the config with method: "sftp").

For example, if getContract returns:

{
  "deliveryLocations": [
    {
      "method": "sftp",
      "path": "folder1/"
    }
  ]
}

And listDeliveryLocationConfigs returns:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "method": "sftp",
      "config": {},
      "status": "active"
    }
  ]
}

Then specify the SFTP delivery using the discovered config ID and the path from your contract:

"deliveries": [
  {
    "locations": [
      {
        "configID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "path": "folder1/",
        "subPath": "project1/"
      }
    ]
  }
]
SFTP delivery does not support delivery status webhook notifications. To track delivery status, poll the getTask operation and check the delivery status in the task’s deliveries object, which will show SUCCESS when products are delivered.

Notifications

You can optionally use a webhook to receive a notification whenever the task status changes — for example, to be notified when a tasked image becomes available for download from the delivery location (task status transitions to FULFILLED or DONE).

To use a webhook (which must already be registered with the Notifications API), provide the id of the registered webhook in the notifications parameter, as follows:

"notifications": {
  "webhook": {
    "id": "XXXXXX-XXXXXX-XXXXXX",
  },
},

The notifications flow works as follows:

  1. The webhook (identified by its webhook ID) must already be registered with the Notifications API. To receive the notification callbacks, you must implement a callback HTTPS server.

  2. When you invoke the createTask operation, specify the webhook ID in the notifications parameter.

  3. When the status of the created task changes, the notification service sends a callback message containing the task ID of the updated task to your callback HTTPS server.

  4. Call the getTask operation with the provided task ID to check the updated task status.

For more details, see Notifications.

Example

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/tasking/v2/tasks" \
--header "Content-Type: application/json" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}" \
--data '{
  "acquisitionWindow": {
    "start": "2023-12-29T23:20:11.315Z",
    "end": "2023-12-30T01:20:11.315Z"
  },
  "contractID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "imagingMode": "SPOTLIGHT",
  "pointOfInterest": {
    "lat": -23.700552,
    "lon": 133.882675
  }
}'

Response

On success, customers will receive a 201 status code and a JSON object containing the recently created Task with a RECEIVED status.

{
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "pointOfInterest": {
    "lat": 0,
    "lon": 0
  },
  "acquisitionWindow": {
    "start": "2023-12-29T23:20:11.315Z",
    "end": "2023-12-30T01:20:11.315Z"
  },
  "createdAt": "2023-12-20T15:04:05Z07:00",
  "updatedAt": "2023-12-20T15:04:05Z07:00",
  "imagingMode": "SCAN",
  "contractID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "reference": "customer task reference 123-456",
  "status": "RECEIVED",
  "exclusivity": "PRIVATE",
  "priority": "COMMERCIAL",
  "sla": "SLA_8H",
  "eula": "STANDARD",
  "productsAvailableInSeconds": 2304,
  "productTypes": ["GRD"],
  "incidenceAngle": {
    "min": 10,
    "max": 45
  },
  "lookSide": "LEFT",
  "passDirection": "ASCENDING",
  "imageReference": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX"
}

Errors

This section describes some common error conditions.

400 - bad request

Indicates that the request was malformed.

Example error when the contract budget is insufficient to cover the cost of tasking:

{
    "code": "ERR_INSUFFICIENT_FUNDS",
    "message": "could not create task: insufficient funds"
}

Verify that you are tasking a valid combination of parameters that are compatible with the contract. A quick way to verify is to confirm that you can request a price for the same combination of parameters using the getTaskPrice operation. If you cannot, debug the error using these common error messages.

If you can successfully call the getTaskPrice operation, verify that you have enough funds in your contract to cover the cost of the task. Call the getSummary operation to check your current balance. Calculate your remaining funds as outlined in the section available funds.

For more details, see Error handling.

422 - unprocessable content

Example error when the request was badly formed:

{
    "code": "ERR_INVALID_CONTRACT",
    "message": "could not create task: invalid model: invalid contract"
}

Please verify the contract is still active by checking its start and end using the GetContract operation. If your contract has expired, reach out to your sales representative to enter into a new contract negotiation.