Planet’s Tasking API is a programmatic interface that enables customers to manage and request imagery collection in an efficient and automated way. With the Tasking API, customers can:
- Create, edit, and cancel SkySat point collection orders
- Get the status of their order and check the collection progress
- View metadata on the images tasked in attempt to fulfill of their order
Automated Tasking currently supports Point, Stereo and Area Tasking Orders. As we continue to improve our capabilities, we plan to support additional order types (video, bulk orders, etc.).
Key Concepts
Order: A request to obtain imagery of a single contiguous area of interest.
Order Status: A representation of where an order is at in its lifecycle – from creation and collection to order fulfillment.
Capture: An image which was tasked in an attempt to fulfill an order. There is currently a one-to-many relationship between orders and captures, as an order may need to be tasked multiple times in order to meet cloud cover specifications or other fulfillment criteria. A given capture may or may not fulfill any order.
Capture Status: A representation of where a capture is at in its lifecycle – from uplink to satellite to publication to the ordering customer and the SkySat Archive.
Capture Assessment: A representation of whether a capture meets the order’s specifications, thereby fulfilling an order.
Archive Publication Time Period: the time between when a capture is published to the customer who ordered the imagery and the published to the SkySat archive.
Order Status
After an order has been entered, you may check the Tasking API for the status of that order. The diagram below outlines how orders flow through the system.

- Pending: The order has been accepted and its start time has not yet passed.
- In Progress: The order’s start time has passed and it is ready to be scheduled. Time in this state will depend on local cloud cover and collection capacity. Orders that have taken captures which did not meet specifications will stay in
In Progress
while they are retasked. - Fulfilled: The order has a capture which meets fulfillment specifications.
- Cancelled: The order was cancelled. Orders may be cancelled if they are
Pending
orIn Progress
, however captures alreadyQueued
,Processing
orPublished
at the time of cancellation, may still be subject to charge (see Capture Status for details). - Expired: The order’s end time has passed, all of its captures have been
Published
, and none meet specifications. The order will no longer be scheduled for imaging. - Failed: The order failed.
Order Status Example
To see the status of your order, you can make GET request for your order id. You can also filter orders by additional order metadata. See our API reference for more information.
Endpoint
https://api.planet.com/tasking/v2/orders/?status=FULFILLED
Response example
{
"id": "bfc45520-8a72-4d23-bfd1-7b22f23ed133",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-77.306467,
45.435827
],
[
-77.229787,
45.435827
],
[
-77.22975,
45.489812
],
[
-77.306504,
45.489812
],
[
-77.306467,
45.435827
]
]
]
},
"capture_count": 2,
"capture_status_queued_count": 0,
"capture_status_processing_count": 0,
"rank": 1,
"start_time": "2019-09-30T20:30:50.836516Z",
"end_time": "2020-09-27T23:59:59.999000Z",
"created_time": "2019-09-30T20:30:51.807703Z",
"name": "cairo_egypt",
"status": "FULFILLED"
}
Capture Status
As described under Key Concepts, an order may have multiple captures, as multiple collections may be required to acquire an image which meets your specifications (cloud cover, etc.).
Each capture of an order has a status, so that you may follow along with where that capture is at in its lifecycle to inform expectations on acquisition or when an image might be published. The diagram below outlines how captures flow through the system.

- Queued: The capture has been created and sent to a satellite. It will be imminently acquired and downlinked.
- Processing: The capture has been downlinked and is in our processing pipeline.
-
Published:
- Captures are published first to the customer who ordered the image. Only other users in this user’s organization may see this collect during this archive time period.
- After the Archive Time period elapses the imagery is published to all customers who have purchased the SkySat archive.
-
Failed: The capture has failed to be captured or failed in processing.
Capture Status Example
To see the status of your order’s captures, you can make a GET request for captures, filtering by order id(s). You can also filter by additional capture metadata. See our API reference for more information.
Endpoint
https://api.planet.com/tasking/v2/captures/?order_id=<order-id>
Response example
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "1e0268d2-8c96-49ed-b809-eceafa563950",
"assessment": "SUCCESS",
"updated_time": "2019-09-21T23:57:43.783444Z",
"acquired_time": "2019-09-21T08:51:31.094000Z",
"published_time": "2019-09-21T23:57:43.783444Z",
"status": "PUBLISHED",
"status_description": null,
"strip_id": "s104_20190921T085131Z",
"cloud_cover": 0.16,
"item_types": [
"SkySatScene",
"SkySatCollect"
]
}
]
}
Retasking & Assessment
If an order’s capture does not meet specifications, it will be retasked until its end time expires. Multiple captures may be collected for an order to satisfy its cloud cover and collection requirements. As captures are collected they are algorithmically assessed for cloud cover and may also be subject to another round of human-in-the-loop review.
A capture will be assessed as SUCCESS
if cloud cover is less than or equal to your contractual cloud cover specifications. If a capture meets specifications, its order’s state will change from IN PROGRESS
to FULFILLED
.
A capture will be assessed as INVALID
if cloud cover exceeds contractual specifications. If a capture is invalid, its order’s state will stay in REQUESTED
and be retasked if its end time has not passed, or transition to EXPIRED
if its end time has passed.
Note that as part of our human-in-the-loop review, a capture evaluated by the system may be manually reassessed, which may cause its order’s state to change. For example, a capture the system marked as SUCCESS
may be manually reviewed as INVALID
changing its order’s state from FULFILLED
to IN PROGRESS
(or EXPIRED
). Similar order state changes would be expected for a capture marked INVALID
which was manually reviewed as a SUCCESS
. Typically any manual review happens within 24 hours of capture publish and changes to an order’s state due to manual assessment after this time are unlikely.
Standard delivery & archive
An integral part of the Planet hi-res sevice is the concept of exclusive access to the captures that may be retrieved as part of a Tasking Order. When you create a tasking order, this exclusivity period will be applied to all captures that are produced as part of that tasking order, ensuring that only you have access to those captures for the duration of the exclusivity period. The standard duration for the exclusive access period is 30 days, after which time the captures will be moved into the public archive.
The Tasking Dashboard will display the date that an image will lose its exclusivity, but if you want to calculate this yourself or are an API user, this is possible using the following method:
- Retrieve the order via the
v2/orders/{order_id}
endpoint. The reponse will include a field calledexclusivity_days
, which indicate the exclusivity period for captures attributed to that tasking order - Then make a second call to
v2/captures/?order_id={order_id}&status=PUBLISHED
which will return all captures for the given tasking order that have been published - For each returned capture, take the date stored in the
acquired_time
field and add the number ofexclusivity_days
to it to find the date when that capture's exclusivity period will end. E.g. If theacquired_date
is 2020-10-10T12:00:00 and theexclusivity_days
value is 30, then the exclusivity period for that capture will end on 2020-11-09T12:00:00
Limits
In order to safely scale use of the Tasking API in Beta, each organization using the Tasking API will have configurable system limits. Please check in with your Account Manager to confirm what your organization’s limits are.
Maximum active orders refer to the number of orders you may have in PENDING
or REQUESTED
states.
Maximum order duration may not exceed your contract duration or 1 year (whichever ends earlier).
Orders that are submitted which hit the maximum active order limit or exceed maximum order duration will return a 400 Bad Request response.
API Access
The Tasking API is currently in Beta. To determine whether you qualify for early access, please reach out to your Account Manager.
The Tasking API uses Basic HTTP Authentication and requires that you have a Planet API key. To read more about how to authenticate with the Tasking API, visit the Tasking Examples page for this and examples on how to create orders and much more.
Rate this guide: