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.

SLA_1H

Promises availability of standard image products within 1 hour of the satellite acquiring the image in certain regions.

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 check whether derivatives are available for the proposed task parameters by specifying the derivativeProductTypes parameter in a feasibility request.

Derivative products are automated detection and classification outputs generated from SAR imagery, identifying and locating objects of interest in the scene.

Currently, only one derivative product type is available:

  • DC-ATR — Automated Target Recognition (ATR): detection and classification of objects of interest (aircraft, vessels, vehicles)

D&C is available only for specific imaging modes, and your contract must allow the required product for the selected mode. Contact your ICEYE representative for any changes needed.

D&C uses the GRD or GRD-COG product as input, so you must include it explicitly in the productTypes parameter. Having it as a default product on your contract is not sufficient.

For a step-by-step walkthrough of requesting, monitoring, and retrieving D&C results, see the Detect & Classify guide.

The legacy types DC_AIRCRAFT, DC_VESSELS, and DC_VEHICLES are no longer supported — use DC-ATR instead. See the deprecation notice for migration details.

For example, to check feasibility with ATR detection derivatives:

"imagingMode": "SPOTLIGHT_EXTENDED_DWELL",
"productTypes": ["GRD"],
"derivativeProductTypes": ["DC-ATR"]

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

  • The request uses the deprecated derivative types DC_AIRCRAFT, DC_VESSELS, or DC_VEHICLES (ERR_LEGACY_DC_DERIVATIVE_TYPES_UNSUPPORTED) — use DC-ATR instead

404 - not found

Indicates that a contract was not found.