Check task feasibility

POST /tasking/v2/feasibility

Use the Feasibility endpoint to validate whether proposed tasking requests can be scheduled by the ICEYE constellation before creating tasks. When a pricing model is included in your contract, it also checks whether the requests fit within your budget. The request takes a list of tasks as input with the same input fields as createTask.

Required parameters

The required parameters of the tasking checkFeasibility operation are specified in the request body of a POST operation. Each task request in the array must include the following required fields:

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

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",
All tasks in a single request must have the same priority

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 as per the policy described in the ICEYE Product Specification.

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.

If not provided, defaults to the contract’s default exclusivity, or PRIVATE if not configured.

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

"exclusivity": "PRIVATE",

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",

Incidence angle

The incidenceAngle parameter specifies the range of incidence angles that are accepted by this task. You can specify numeric values (integers in degrees) or string modes (FULL_RANGE, PERFORMANT).

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

Alternatively, use string modes to optimize for acquisition speed or image quality:

"incidenceAngle": {
  "min": "FULL_RANGE",
  "max": "PERFORMANT"
}

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, you can use either numeric values (integers) or string modes for min and max:

  • Numeric values — specify a range in degrees (e.g., "min": 10, "max": 45). We recommend choosing 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.

  • String modes — use FULL_RANGE to optimize for fastest possible acquisition, or PERFORMANT to optimize for the highest image quality. These modes allow the system to automatically adapt to the capabilities of each satellite generation without requiring manual numeric range adjustments.

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. Defaults to ANY.

"lookSide": "ANY",

Pass direction

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

"passDirection": "ASCENDING",

Derivative product types

You can include derivativeProductTypes in each feasibility request to validate whether derivative processing is available for the proposed task parameters. The feasibility check will verify imaging mode compatibility and contract permissions for the requested derivatives.

Derivative products are automated detection and classification outputs generated from SAR imagery. These products provide valuable insights by identifying and locating specific objects of interest in the scene.

The following derivative product types are available:

  • DC_AIRCRAFT — Aircraft detection and classification

  • DC_VESSELS — Vessel/ship detection and classification

  • DC_VEHICLES — Vehicle detection and classification

Derivatives can only be requested for tasks using high-resolution imaging modes:

  • SPOTLIGHT_EXTENDED_DWELL

  • SPOTLIGHT_EXTENDED_DWELL_FINE

  • SPOTLIGHT_FINE_1L

  • SPOTLIGHT

  • SPOTLIGHT_FINE

When requesting derivatives, you must explicitly include GRD in the productTypes parameter, and your contract must allow the GRD product for the selected imaging mode.

For example, to check feasibility with aircraft detection derivatives:

"imagingMode": "SPOTLIGHT",
"derivativeProductTypes": ["DC_AIRCRAFT"]

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/feasibility" \
--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, returns a 200 status code and a JSON object containing the feasibility results.

{
  "createdAt": "2023-12-29T23:20:11.315Z",
  "feasibility": [
    {
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "status": "FEASIBLE"
    }
  ],
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "status": "DONE"
}

Errors

This section describes some common error conditions.

400 - bad request

Indicates that the request was malformed. Please verify the request body and the spelling and case of the parameters.

403 - forbidden

Indicates that the request is not allowed. Reasons for this error include, but are not limited to:

  • The contract dates are not valid

  • The acquisition window is not valid

  • Derivatives are not enabled for contract

404 - not found

Indicates that a contract was not found.