Task derivatives

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

Derivative products are automated detection outputs that identify and classify objects of interest in SAR imagery using machine learning models. After a task is fulfilled and derivative processing is complete, you can retrieve the derivative products and their associated files.

About derivative products

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.

How it works

The derivative processing workflow follows these stages:

  1. Task creation — When creating a task with derivativeProductTypes, derivative requests are registered for processing.

  2. Image acquisition — After the satellite captures the image, the system processes the standard SAR products including the GRD product required for derivatives.

  3. Derivative processing — Once the GRD product is available, machine learning models automatically process the imagery to detect and classify objects of interest.

  4. Product availability — Processed derivative products become available as GeoJSON files through the derivatives endpoint with secure download URLs.

Processing time varies depending on the derivative type and system load. Products may become available at different times, resulting in partial availability (206 status code).

Supported imaging modes

Derivatives are only available for following imaging modes:

Imaging Mode Description

SPOTLIGHT_EXTENDED_DWELL

Extended dwell spotlight mode with maximum resolution

SPOTLIGHT_EXTENDED_DWELL_FINE

Fine resolution extended dwell spotlight mode

SPOTLIGHT_FINE_1L

Fine resolution single-look spotlight mode

SPOTLIGHT

Standard spotlight mode

SPOTLIGHT_FINE

Fine resolution spotlight mode
Attempting to request derivatives for other imaging modes (e.g., STRIPMAP, SCAN) will result in a 400 Bad Request error with code INCOMPATIBLE_IMAGING_MODE_FOR_DERIVATIVES.

Derivative availability

The derivatives endpoint returns different HTTP status codes depending on product availability:

  • 200 OK — All requested derivatives have products available

  • 206 Partial Content — Some, but not all, derivatives have products available

  • 404 Not Found — No derivative products are available yet

This allows your application to handle partial availability scenarios and distinguish between processing delays and tasks without derivatives.

Get derivatives

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 or 206 status code and a JSON object containing the list of derivatives with signed URLs for downloading the product files.

Download URLs expire in 1 hour. Do not store the URLs for long term access.
Open code example 
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "imageReference": "c2ac555e-27ac-4c6a-bf87-717fa81539e3",
      "derivativeProductType": "DC_AIRCRAFT",
      "assets": [
        {
          "type": "geojson",
          "href": "https://d1234567890abc.cloudfront.net/abc-123-def/aircraft-detections.geojson?Expires=1234567890&Signature=..."
        }
      ]
    },
    {
      "id": "7fb95g75-6828-5673-c4gd-3d074g77bgb7",
      "imageReference": "c2ac555e-27ac-4c6a-bf87-717fa81539e3",
      "derivativeProductType": "DC_VESSELS",
      "assets": [
        {
          "type": "geojson",
          "href": "https://d1234567890abc.cloudfront.net/abc-123-def/vessel-detections.geojson?Expires=1234567890&Signature=..."
        }
      ]
    }
  ]
}

Response fields

  • 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_AIRCRAFT, DC_VESSELS, or DC_VEHICLES)

  • assets — Array of downloadable files for this derivative

    • type — File format (typically "geojson")

    • href — Signed CloudFront URL for downloading the file

Handling partial availability

When the response status is 206 Partial Content, some derivatives are still being processed. Your application should check which derivative types have assets available and poll the endpoint again later for the remaining products.

In the following example response with partial content (206), the DC_AIRCRAFT derivative has an empty assets array indicating it is still being processed, while DC_VESSELS already has downloadable products:

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "derivativeProductType": "DC_AIRCRAFT",
      "assets": []
    },
    {
      "id": "7fb95g75-6828-5673-c4gd-3d074g77bgb7",
      "derivativeProductType": "DC_VESSELS",
      "assets": [
        {
          "type": "geojson",
          "href": "https://d1234567890abc.cloudfront.net/..."
        }
      ]
    }
  ]
}

Error responses

The derivatives endpoint may return the following errors:

Status Code Description

401

Missing or invalid authentication token

403

Insufficient permissions to access this task’s derivatives

404

Task not found, no derivatives were requested for this task, or no derivative products are available yet (still processing or GRD product not available)

429

Rate limit exceeded

500

Unexpected server error

Resources