Task derivatives

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

Derivative products are automated detection outputs that identify and classify 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 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.

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 (DC-ATR)

assets

Array of downloadable files for the derivative. Each asset has a type (file format, typically geojson) and an href (signed CloudFront URL for downloading the file).

The internal structure of the D&C GeoJSON files — the specific fields and what they mean — is shared on an individual basis. Reach out to your ICEYE representative for the detailed schema.

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": "DC-ATR",
      "assets": [
        {
          "type": "geojson",
          "href": "https://d1234567890abc.cloudfront.net/abc-123-def/detections.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