Overview

The Tasking API provides the tools for submitting and checking the status on imagery product collection — a tasking order. This service enables:

the creation of tasking orders
the retrieval of the order status and the collection progress
the cancellation of existing orders

Once users have been authenticated, they can proceed to submit a task using the provided token.

What is a task?

A task is a request from a user to capture a single target one or many times in a given period. In other words, it is a request to generate a set of captures over the target that during the period where the Task is active, will cover the target a specific amount of times.

Task main attributes

Here we list the basic and mandatory attributes for a Task. From this basis, you can include additional attributes to tune your Task in different ways.

Parameter	Type	Description
target	GeoJSON	Each Task is related to a single target. The target is a geographical polygon represented as GeoJSON. For POI product, the target must be a point. For AOI product, the target must be a polygon.
start	ISO Datetime	Tasks must specify a `start` and `end`. Those two attributes define the period where the Task will be active. After the period ends, the system will not generate any additional capture for the Task, regardless if the user obtained all the expected captures or not.
end	ISO Datetime	End of the task's period (see the `start` paremeter description)
product_id	integer	There are two types of products available for tasks: POI: to capture stripes & AOI: to capture an entire area in multiple stripes. To use each product, make sure your user has permission.
task_name	string	An identifier for the task
project_name	string	An identifier for the project related to the task (created under the hood).

Task Lifecycle

A task is always linked to a status indicating the stage in the lifecycle where the task is. When a task is created, the first status is always received. This means the task was created, and it will be considered in the planning process. We still can not say if the captures for the task will be planned or not. After the planning process finishes, there are two possible scenarios:

If the planning process generated planned captures for the task, then it will be moved to pending
If the planning process didn't generate planned captures for the task, then it will be moved to planning

Once the capture has planned captures and is in pending status, it will be moved to in_progress 12 hours before the first capture takes place.

A task in in_progress status will be moved to completed once all the requested captures are completed (see the max_captures parameter definition). In case the task's end date is reached and not all the requested captures are completed the project will be moved to failed.

Additionally if the user cancels the task. The status will change to canceled.

Task states

State	Description
received	The task was created, and it will be considered in the planning process. We still can not say if the captures for the task will be planned or not.
pending	The planning process considering the task was finished and generated planned captures on behalf of the task.
rejected	The feasibility analysis indicates we can not fulfill your order due technical reasons. Most likely we can not accomplish ONA and/or sun angle restrictions.
planning	The planning process finished, but it didn't generate any planned captures on behalf of the task.
in_progress	The task has planned captures for the future. The first planned capture has yet to happen and will happen in 12 hours or less. It is also possible the first capture already happened, and it will be more planned captures in the future.
canceled	A user manually canceled the task. The planned captures will be canceled (if possible). The task may have past captures already delivered.
failed	The task's period ended but none of the requested captures were taken. The order was not fulfilled.
completed	All the requested captures were captured. The order was fulfilled.
partially_completed	Some (but not all) the requested captures were captured. The order was partially fulfilled.

Task captures

The previous section explained the task states and their relationship with planned and past captures.

But what is it a capture? What are planned captures and past captures?

A planned capture is a capture that we plan to take. It is the compromise of taking a capture on behalf of a task in the future.

A past capture occurred in the past, and it's being processed or already delivered to the client.

When a capture fails during any stage of the capturing, processing, and delivering process, it becomes a failed capture.

The capture status defines whether a task is planned, past, or failed.

State	Description
queued	The capture is planned, and it will happen in the future. A capture in this state is considered a "planned capture".
failed	Something failed, and the image can not be delivered. The failure can be at any stage of the process: during camera command execution, file downloading, or image processing. It is possible that the image was delivered, but for some reason, it was not usable for the final client and they decided not to approve them. All captures in failed status will be re-planned as long as the task is active (inside the task period).
processing	The capture was taken and is being processed. This state covers the execution of the camera command up to the final image delivery, considering all the processing steps to generate that image.
published	The capture was delivered, and the final client approved it. A capture in published status is considered a success case to fulfill the task.

The state of a planned capture is always queued. It's start date is always in the future, but under certain circumstances, it may happen that captures in status queued had a start date in the past. The reason is the lack of evidence that the satellite executed the capture as expected. The situation should be normalized within 24 hours of the capture start date.

A capture in processing or published status is a past capture, meaning it is useful to fulfill the order, is valuable for the client, or is still being processed.

Under any unexpected circumstances, if any failure happens during capture, processing, delivering, or if for any reason the capture is not valuable for the client, the status will be failed corresponding to a failed capture.

Tasking using the Objects In Space dedicated endpoint

OIS (Objects in space) is a type of product that allows capturing orbital targets (instead of land targets).

To create an OIS, first, you need to know the product ID corresponding with OIS. You also must ensure your user is allowed to use the product and use the /ois/ endpoint.

As opposed to other tasks types where the satellite executing the capture and the date and time where the capture will take place are given by the planning process, in OTS tasks you must specify several details, according to the type of maneuver that will be used to make the capture.

The regular way of making OIS is made with the spotlight method. This method requires two parameters: capture_at with the date and time of the capture to be made, and target, specifying the point. We also provide support to use the evo stripe maneuver in OIS captures. This maneuver requires a start_point and a direction_point, as well as date and time to start the capture in the form of the parameter time_at_start_point and the expected ground_speed, expressed in km/s. We also accept an optional parameter of duration, which should be specified in seconds. All the points should be in GeoJSON format. All of the parameters for the maneuver go in the field maneuver_params

There's another optional parameter (outside of maneuver parameters), called absolute_exposure, specified in microseconds, which allows to customize the exposure time of the image. Values for this parameter should be an integer number between 410 and 6000. Please only use this parameter if you know exactly the value.

Captures for OIS tasks can be obtained using the regular tasking API endpoints.

Change log

Tasking API v1.5.3

February 01, 2024

Adds the dedicated OIS tasking endpoint, with support for both Spotlight and EVO maneuvers

Tasking API v1.5.0

September 27, 2023

Adds quality parameters for off nadir and sun angle.
Adds the fragments endpoint.

Deletions:

Removes the already deprecated rating parameter.

Delivery Service Update

September 20, 2023

Remove task and project names from Scene metadata. Task and project id values are still available in the Scene metadata to reconciliate the human readable names from the Tasking Service if needed.

Deletions:

metadata.task_name field was deleted from the scene detail response.
metadata.project_name field was deleted from the scene detail response.

Analysis API v1.2.1

September 11, 2023

Adds the Opportunities Analysis API to understand capture opportunities for a task's payload.

Tasking API v1.4.1

July 17, 2023

Add optional absolute_exposure parameter to the Task Object, this parameter should only be used when creating tasks for OTS product.

Tasking API v1.4

July 11, 2023

Tasking API v1.4 deprecates rating parameter to make way for new priority parameter allowing for a single client to assign a specific priority to an order from a previously arranged priority range. It also adds the client parameter needed for accounts that manages multiple clients. Finally, it includes a new clients endpoint that returns account information including allowed priority range (min, max and default).

Features:

priority parameter addition to the Task Object, affecting all endpoints that return a Task. Value is integer, parameter is optional.
client parameter addition to the Task Object, affecting all endpoints that return a Task. Value is string, parameter is optional. Only needed if the account has more than one client.
New endpoint /clients/ exposing configuration for the account, and available priority values.

Deprecations (ignored parameters, for now):

rating parameter will no longer have effect although it will still be accepted in the request, and continue to be returned as part of the Task payload for the different endpoints. This parameter will be removed in a follow-up release.

Tasking API v1.3.1

June 1, 2023

Tasking API v1.3.1 removes parameters that were deprecated in v1.2.

Changes:

Successful Task creation now responds with http status code 201 instead of 200.
GET requests containing a payload body now return a 400 error.

Deletions:

sceneset_id field was deleted from the task detail response but will be possible to obtain a complete list of captures related to a task from the Captures endpoint.
expected_date, expected_remap_days and age read-only fields were deleted from the task details response.

Tasking API v1.3

April 26, 2023

Tasking API v1.3 introduces a new task status workflow.

Features:

Adds an improved, detailed, and backward-compatible status workflow for tasks to ensure customers can track their orders’ progress through the Tasking API. For example, a task will be rejected before being published if it’s somehow not feasible, or it’ll be possible to know if it’s partially completed based on its status.

Tasking API v1.2

December 1, 2022

Tasking API v1.2 deprecates parameters and makes start and end parameters mandatory.

Features:

start and end dates parameters are now mandatory for all tasks.

Deprecations (ignored parameters, for now):

sceneset_id field was deprecated from the task detail response but will be possible to obtain a complete list of captures related to a task from the Captures endpoint.
expected_date, expected_remap_days and age read-only fields were deprecated from the task details response.

Last update: 2024-11-01