Get task scene

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

You can invoke the getTaskScene operation with a particular taskID task, to discover the planned imaging time (and other imaging parameters) for the task. Because the ICEYE scheduler is continually updating and optimizing tasking opportunities, the scene parameters are liable to change over time, becoming more accurate as it gets closer to the planned acquisition time.

If you need to submit tasks well in advance (up to 14 days), the getTaskScene operation makes it possible to get an accurate estimate of the imaging time, by polling for the scene parameters closer to the planned imaging time.

Polling scene parameters

Scene parameters can provide details of the imaging parameters for the currently planned tasking opportunity.

Scene parameters

The following scene parameters are provided in the getTaskScene response:

Scene parameter Description

Scene parameter	Description
`imagingTime`	Currently planned start time (`imagingTime.start`) and end time (`imagingTime.end`) of the imaging operation, according to the selected tasking opportunity (in RFC 3339 format).
`duration`	The predicted duration of the imaging acquisition (in seconds).
`lookSide`	Look side for the currently selected tasking opportunity (`LEFT` or `RIGHT`).
`passDirection`	Pass direction for the currently selected tasking opportunity (`ASCENDING` or `DESCENDING`).
`incidenceAngle`	(COMING SOON) Incidence angle for the currently selected tasking opportunity.

imagingTime

Currently planned start time (imagingTime.start) and end time (imagingTime.end) of the imaging operation, according to the selected tasking opportunity (in RFC 3339 format).

duration

The predicted duration of the imaging acquisition (in seconds).

lookSide

Look side for the currently selected tasking opportunity (LEFT or RIGHT).

passDirection

Pass direction for the currently selected tasking opportunity (ASCENDING or DESCENDING).

incidenceAngle

(COMING SOON) Incidence angle for the currently selected tasking opportunity.

Note that all of these parameter values are liable to change over time, as the ICEYE scheduler continuously optimizes tasking activities. Once the scene has been acquired, the parameters are locked at their final values.

Availability of scene parameters

Scene parameters are dependent on the task status and are thus not always available for polling. The following factors affect the availability of scene parameters:

Task feasibility — a task must have passed the initial feasibility checks and transitioned from RECEIVED to ACTIVE.
Task status — must be ACTIVE, FULFILLED, or DONE
Task cancellation — scene parameters are no longer available after task cancellation.
Task fulfillment — the scene parameters returned after task fulfillment correspond to the parameter values that were used for the acquisition.

Scene parameters can be updated fairly frequently before the planned imaging time, reflecting the following kinds of changes:

The ICEYE scheduler identifes new tasking opportunities.
Imaging activities getting rescheduled due to optimization, orbit drift, satellite anomalies, and so on.
A satellite has uploaded new instructions for the imaging activies.

Accuracy of imaging time

Because of orbit unpredictability, if you submit a task 7 - 14 days before the acquisition window start time, the planned imaging time is likely to be modified. As you poll the getTaskScene operation closer to the planned imaging time, however, the accuracy continuously improves.

The following table shows how accuracy improves as you poll closer to the planned imaging time.

Time till imaging start	Accuracy (+/- 90 seconds)	Description
7 to 14 days	N/A	The task will be completed with 90%+ reliability, but there’s a high likelihood the scheduler will change the imaging time. We recommend checking back at 7 days before acquisition for more accurate information.
3 to 7 days	50%	The task will be completed with 90%+ reliability, and there’s a 50%+ likelihood the scheduler does not change the imaging time.
less than 3 days	80%	The task will be completed with 90%+ reliability, and there’s an 80%+ likelihood the scheduler does not change the imaging time.

Time till imaging start

Accuracy (+/- 90 seconds)

Description

7 to 14 days

N/A

The task will be completed with 90%+ reliability, but there’s a high likelihood the scheduler will change the imaging time. We recommend checking back at 7 days before acquisition for more accurate information.

3 to 7 days

50%

The task will be completed with 90%+ reliability, and there’s a 50%+ likelihood the scheduler does not change the imaging time.

less than 3 days

80%

The task will be completed with 90%+ reliability, and there’s an 80%+ likelihood the scheduler does not change the imaging time.

A planned imaging time is defined to be accurate, if the acquired imaging time ultimately lies within +/- 90 seconds of the planned imaging time.

Reliability and accuracy estimates are valid only for tasks with at least COMMERCIAL priority. Tasks with BACKGROUND priority do not come with any guarantees of reliability or accuracy.

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}/scene" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}"

Response

On success, returns a 200 status code and a JSON object containing the task scene.

{
  "duration": 60,
  "imagingTime": {
    "start": "2023-12-29T23:20:11.315Z",
    "end": "2023-12-29T23:21:11.315Z"
  },
  "lookSide": "LEFT",
  "passDirection": "ASCENDING"
}

Errors

This section describes some common error conditions.

404 - not found

Indicates that the requested scene is unavailable because the task is currently not scheduled. This could occur for the one of the following reasons:

The task status is RECEIVED, CANCELED, or FAILED.
The scheduler is in-between assigning a new opportunity (or searching for one).