Get task

GET /tasking/v1/tasks/${taskID}

Customers can periodically poll the Tasking API to retrieve the latest status of their task with their taskID. Tasks are updated until they reach a final status.

Task lifecycle

Task Status

  1. The Tasking API verifies a submitted task and then adds it to the queue as RECEIVED.

  2. An optimizer runs within the next 20 minutes. If the submitted task has a high probability of being acquired, the Tasking API updates the task status to ACTIVE. Otherwise, the task is REJECTED.

  3. An ACTIVE task can be canceled, if necessary, by calling Task Cancellation.

  4. When the Standard SAR Data Products become available, an ACTIVE task transitions to FULFILLED (or straight to DONE, if there are no additional products).

  5. If a task includes any non-standard SAR data products (see Additional product types), the task remains in the FULFILLED state while the non-standard products are processed.

  6. The task transitions to DONE after all requested SAR Data Products are available.

  7. When ICEYE fails to collect an ACTIVE task, the status transitions to FAILED

Task status

Task Status Description Transitions To

RECEIVED

ICEYE is trying to determine the probability of task success

REJECTED, ACTIVE, CANCELED

ACTIVE

ICEYE estimates there is a high probability of task success and has accepted the task

FULFILLED, DONE, CANCELED, FAILED

FULFILLED

Standard products are available to download. Requested non-standard product may still be processing

DONE

DONE

All requested product types (standard and non-standard), are available to download

-

REJECTED

ICEYE has rejected the task due to low confidence in being able to fulfill it

-

FAILED

ICEYE failed to collect the image data for an unusual reason (for example, unplanned satellite maintenance)

-

CANCELED

The user canceled the task

-

Example

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

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

Response

On success, customers will receive a 200 status code and a JSON object containing the desired Task and its information.

{
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "pointOfInterest": {
    "lat": 0,
    "lon": 0
  },
  "acquisitionWindow": {
    "start": "2023-12-29T23:20:11.315Z",
    "end": "2023-12-30T01:20:11.315Z"
  },
  "createdAt": "2023-12-20T15:04:05Z07:00",
  "updatedAt": "2023-12-20T15:04:05Z07:00",
  "imagingMode": "SCAN",
  "contractID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "reference": "customer task reference 123-456",
  "status": "RECEIVED",
  "fulfilledAt": "2023-12-30T00:04:05Z",
  "exclusivity": "PRIVATE",
  "priority": "COMMERCIAL",
  "sla": "SLA_8H",
  "eula": "STANDARD",
  "productsAvailableInSeconds": 2304,
  "additionalProductTypes": [
    "SIDD",
    "SICD"
  ],
  "incidenceAngle": {
    "min": 10,
    "max": 45
  },
  "lookSide": "LEFT",
  "passDirection": "ASCENDING"
}

Tasks from preexisting contracts

Before the Tasking API release in May 2024, ICEYE had a slightly different structure for tasks and contracts. Both the priority and sla were added as part the new suite of APIs. All tasks created using preexisting contracts have these fields generated and populated automatically with the following defaults:

  • priority as COMMERCIAL

  • sla as SLA_8H