Task derivatives

GET tasking/v2/tasks/{taskID}/derivatives

Derivative products are automated detection outputs that detect and identify objects of interest in SAR imagery. You can retrieve them from the Tasking API once the task status is FULFILLED or DONE.

  • FULFILLED — Derivatives are available if they are covered by an SLA product on your contract.

  • DONE — All requested derivatives are available, including those not covered by an SLA.

Derivative products

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

The following derivative product types are available:

  • ODI — Object Detection and Identification (ODI): detection and identification of objects of interest (aircraft, vessels, vehicles). Request this type going forward.

  • DC-ATR — deprecated, will be removed on January 4, 2027. Until then it is still accepted and delivers the previous output: a _DC.geojson file in the previous GeoJSON format. Use ODI instead.

Delivered files

Results are GeoJSON files named from the source GRD or GRD-COG product, following the ICEYE file naming convention. The suffix identifies the derivative type:

Derivative product type File suffix Example

ODI

_ODI.geojson

ICEYE_SZFYKK_20261001T000000Z_1234567_X52_SLEDF_GRD_ODI.geojson

DC-ATR

_DC.geojson

ICEYE_SZFYKK_20261001T000000Z_1234567_X52_SLEDF_GRD_DC.geojson

The signed download URL in each asset href uses this filename.

ODI 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 ODI results, see the Object Detection and Identification guide.

ODI and DC-ATR can be requested only with these imaging modes:

Supported imaging modes for derivatives

  • SPOTLIGHT_EXTENDED_DWELL

  • SPOTLIGHT_EXTENDED_DWELL_FINE

  • SPOTLIGHT_EXTENDED_DWELL_PRECISE

  • SPOTLIGHT_FINE

Requests with any other imaging mode fail with 400 Bad Request and code ERR_INCOMPATIBLE_IMAGING_MODE_FOR_ATR_DERIVATIVES. Your contract must also allow the required product for the selected mode. Contact your ICEYE representative for any changes needed.

Availability

You request derivatives at task creation with the derivativeProductTypes parameter, then retrieve them from this endpoint once they are ready. Wait on the task status rather than polling this endpoint. A request made once your derivatives are ready returns 200. A 404 means it was queried before the products were ready.

Response fields

The response returns a list of derivatives under data. Each derivative contains the following fields:

Field Description

id

Unique identifier for the derivative processing request

imageReference

UUID reference to the source image

imageID

Alternative string identifier for the source image (optional)

derivativeProductType

Type of derivative product (ODI, DC-ATR if the task was requested with the deprecated type, or a historical DC_AIRCRAFT / DC_VESSELS / DC_VEHICLES value on stored records)

assets

Array of downloadable files for the derivative. Each asset has a type (file format, typically geojson) and an href (signed URL). The filename in href is the source GRD basename plus _ODI.geojson for ODI, or _DC.geojson for DC-ATR.

For the file naming, the GeoJSON schema version, and the detection fields, see Reading the ODI GeoJSON output.

Example

Request

To get the derivative products for a task, enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/tasking/v2/tasks/${taskID}/derivatives" \
  --header "Accept: application/json, application/problem+json" \
  --header "Authorization: Bearer ${API_ACCESS_TOKEN}"

Response

On success, the response returns a 200 status code and a JSON object containing the list of derivatives with signed URLs for downloading the product files.

Open code example 
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "imageReference": "c2ac555e-27ac-4c6a-bf87-717fa81539e3",
      "derivativeProductType": "ODI",
      "assets": [
        {
          "type": "geojson",
          "href": "https://d1234567890abc.cloudfront.net/abc-123-def/ICEYE_SZFYKK_20261001T000000Z_1234567_X52_SLEDF_GRD_ODI.geojson?Expires=1234567890&Signature=..."
        }
      ]
    }
  ]
}
Download URLs are signed and expire after 1 hour. Do not store them for long-term access, instead request a fresh URL from the API when you need to download again.

Errors

This section describes some common error conditions.

404 - not found

Indicates that no derivative products are available. Reasons for this error include, but are not limited to:

  • The task was not found.

  • No derivatives were requested for this task.

  • The derivatives are still processing, or the required GRD or GRD-COG product is not yet available.

The endpoint also returns the standard 401 (authentication), 403 (authorization), 429 (rate limit), and 500 (server) errors. See Error handling for the common error format.

Resources

  • ICEYE Derivative Products — Overview of ICEYE’s derivative product offerings, including Object Detection and Identification (ODI)