Introduction

What is a task?

A task is a user-submitted order to acquire new satellite imagery. Tasks are used to request different imagery products, each defined by a specific geometry type and collection logic.

This document outlines general concepts in the tasking workflow, along with product-specific behaviors that may affect how tasks are created and fulfilled.

Tasks and products

The table below summarizes how each product in our offering behaves in terms of geometry type and collection logic, as well as how the product is referenced at the moment of placing a task and whether part of the behavior is controlled by contract settings.

Product Name	Geometry	Collection Logic	product_id in Aleph	Behavior Controlled By
Standard Tasking (POI)	Point	One or more captures over a point with a fixed footprint size (5x5km, 5x10km, etc). The order is typically covered by a single capture, but may include more than one capture in case recurrence is selected. Collection retries within the task may happen in case of collection failure or QC rejection.	API: 169 WEB: Multispectral 70cm	Geometry and collection behavior defined by product_id. Default footprint size, cloud cover threshold, prioritization and timeline defined by contract_id.
Rush Tasking (POI)	Point	Same as above, but with prioritized scheduling and expedited delivery.	API: 169 WEB: Multispectral 70cm	Geometry and collection behavior defined by product_id. Default footprint size, prioritization and timeline defined by contract_id.
Standard Area Coverage (AOI)	Polygon	AOI is fragmented into rectangular strips. Each strip is collected separately, typically on different days. Collection retries within the task may happen in case of collection failure or QC rejection.	API: 178 WEB: Area Coverage 70cm	Geometry and behavior defined by product_id.
NEI (Non-Earth Imaging)	Conjunction-based maneuver	Single, precisely timed capture based on satellite-to-satellite geometry. No retries are possible, as the opportunity is unique and tightly constrained.	API: 186 WEB: N/A	Geometry and behavior defined by product_id.

Note: POI-based tasking (Standard and Rush) uses the same product_id. Scheduling prioritization and timeline are determined by the contract_id provided in the request. The setup of contracts with the appropriate parameters for each product is handled by Account Managers.

Core task parameters

The following minimum parameters are required when interacting with both the Analysis API and Tasking API. Moreover, after getting a satisfactory result from the Analysis API for a given payload, the exact same payload can be used for ordering through the Tasking API.

Parameter	Type	Description
target	GeoJSON	Each Task handles a single target object. * For POI products the GeoJSON must be of type Point. * For AOI products the GeoJSON must be of type Polygon.
start	ISO Datetime	Starting date and time of the collection window. The collection window is the period in which collection of images shall be allocated for the task. This period is defined by the start and end parameters and no collection will be planned outside of this time range. This period should be chosen to be as wide as possible within the user's need.
end	ISO Datetime	Ending date and time of the collection window (see the start paremeter description).
product_id	integer	This is a unique product identifier that refers to the type of geometry and collection logic. To find which is the appropriate id for a given product, see previous section: Tasks and products.
task_name	string	A meaningful identifier for the task or its target. This may be some target identifier or site reference, such as "Target_001" or "Los Angeles Airport Jan 2025". This string may be used later to apply filters when retrieving task lists.
project_name	string	A meaningful identifier that may be used to group more than one task that share a common purpose, user, etc. This may be "Global Airports" or "Mark's tasks".

Note: For full API request schemas see the Tasking API Spec.

The task timeline

The follwing timeline describes key milestones for tasking orders from task creation through collection and delivery, and time-derived metrics that are specified for our products.

The milestones in the upper level of the diagram are user requirements, and the milestones in the lower level of the diagram are a result of our systems' performance while fulfilling the tasking order.

The actual timeline for a particular task may differ from this example. For instance, a task may reach a completed state within the collection window if the capture and delivery were completed before the collection end time, or it may end up on a failed state at the end of the collection time of no collections were successful in the collection period. For full detail on task statuses and the conditions that trigger them see next section Task Statuses.

Definitions for timing SLAs:

• Order cutoff time: This is the minimum time between order placement and the commencement of the collection process. This is typically 6 hours 90th percentile for all our tasking products. Collections do frequently happen before this cutoff time, nevertheless orders placed 6 hours or more in advance for a specific collection opportunity have 90% chances to arrive to the satellite on time. During this period:
  • our planning system is scheduling capture opportunities for the task,
  • the satellite arrives to the uplink location,
  • a collection plan gets uploaded to the satellite,
  • the satellite arrives to the location of interest and starts acquisition.
• Delivery time from collection: This is the time between image collection and the delivery of the image to Aleph platform. Delivery from collection is also specified at 90th percentile for each tasking product. During this period:
  • the satellite arrives to the downlink location,
  • the capture is downloaded (this may require more than 1 downlink opportunity),
  • the capture is processed to the required processing level,
  • the capture is cropped, packaged and published to Aleph platform

Note: These timing performances or SLAs (Service Level Agreements) do not apply individually to each capture, instead measurements are performed monthly by Satellogic.

Task and capture statuses

The Task Lifecycle describes the different phases a task goes through, from the moment it is created until it reaches some terminal state. It includes both the task status — a high-level indicator of where the task is in the ordering and execution process — and the capture status, which reflects the progress and outcome of individual image acquisitions associated with the task.

Understanding these statuses and their transitions is key to interpreting API responses, tracking task progress, and reacting to events such as delivery, re-scheduling, failures, etc.

Task Statuses

The following diagram and table explain the possible statuses for tasks and the events that trigger the transitions between them.

Note: blocks with rounded shape represent terminal statuses, and the ones with cyan color fill are in the path that leads to effective deliveries to the user (COMPLETED and PARTIALLY COMPLETED).

Status code	Description
received	The task submission is acknowledged. The request will enter in the next planning cycle for scheduling of captures. Planning cycles occur every 30 minutes approximately.
planning	The scheduler is searching for capture opportunities for the task. The task shall remain in this state until the planning system schedules/queues a capture. This may take one or several planning cycles depending on the feasibility of the request and on the commercial demand over the time range and location of interest.
pending	The planning system scheduled/queued one or more captures for the task. Permanence in this state is expected while the first queued capture approaches.
in_progress	Transition to this status is triggered by less than 12 hours anticipation to the first queued capture. Permanence in this state is expected during collection, download and processing in ground of the scheduled captures.
canceled	The user manually canceled the task. Queued captures will be removed from the schedule if anticipation from cancelation to queued capture time is enough (more than 12 hours). Although no new collections will happen, it's possible that past captures were published. For instance, if the task required more than one capture to be published, and the collection process is manually interrupted after some captures were successfuly published, then the final status is CANCELED with some published captures.
failed	The task's collection period ended without published captures.
completed	All the required captures were published: * The default amount of captures for a task is one, so once a capture has been published the task switches to COMPLETED, which may happen before the end of collection window. * For tasks that require a fixed number of collections this status is reached when the amount of deliveries matches the requirement (only supported via API using max_captures parameter).
partially_completed	This status is reached when the collection period ended and some captures were published, which is: * For POI tasks that require a fixed number of collections and the amount of deliveries is lower than the requirement (only supported via API using max_captures parameter). * For POI tasks with recurrence, this is the terminal status if at least one capture was published (supported both via API, using expected_age parameter, and via WEB, using "Recurrence" dropdown menu). * For AOI tasks when the amount of published captures does not cover the total amount of fragments of the polygon.

Transitions to PLANNING status

Transition from pending back to planning means that some previously allocated capture is no longer available for the fulfillment of the task. This may happen if:

• a higher priority order is in conflict with this one (eg: Rush Tasking has higher priority than Standard Tasking and Standard Area Coverage),
• the fleet's context or composition changed and the previously allocated capture is no longer feasible: the previously commited satellite was moved to a maintenance state, the satellite's ephemeris was updated and the timing and geometrical constraints are no longer fulfilled by the satellite.

Transition from in_progress back to planning means that capture re-scheduling is needed. This may happen if:

• some capture failed after having progressed through collection, download or processing, and new capture attempts need to be scheduled to fulfill the task.

Captures statuses

Some of the above Task statuses depend on capture-level results, such as "queued capture" or "published capture". The following diagram and table describe the capture status model along with the events that trigger transitions through them.

Note: Blocks with rounded shape represent terminal statuses, and the ones with cyan color fill are in the path that leads to effective deliveries to the user (PUBLISHED).

Status code	Description
queued	A capture in this status is effectively scheduled for collection. Permanence in this state is also expected during capture collection and download.
processing	The capture was successfully collected and downloaded, and it's being processed in ground to yield the required deliverable.
published	The capture was delivered. It's available for download in Aleph's platform (either through WEB or API).
failed	Reasons for capture failure are: * Capture failed during collection or download in orbit. Collection/download failure rate is typically below 5%. * Capture processing in ground to the required processing level could not be completed. Eg: due to the lack of ground reference points (the rate of occurrence here depends on the processing level and the content in the image). * Capture processing to the required level could be completed but it didn't pass QC criteria. Eg: rejected due to cloud cover above threshold, geolocation or band alignment errors above acceptance threshold, etc. All captures in failed status will trigger a re-scheduling as long as there's enough time left within the task collection window.

Tasking API capabilities

Analysis API

The Analysis API is a tool that allows to analyse the feasibility of tasks and their expected outcomes before creating them. It provides two main types of analysis: Opportunities analysis and Can-add analysis.

• Opportunities analysis: Shows all the physically feasible opportunities a task will have, based on our current fleet composition and geometrical constraints in the request's payload. It is intended to answer questions such as:
  • Is this request physically and geometrically feasible to be collected by the fleet with the given constraints (product type, target coordinates, ONA ranges and illumination conditions)?
• Can-add analysis: Shows the available opportunities a new task could actually get considering the commercial demand at the moment of the analysis. It is intended to answer questions such as:
  • What is the actual availability for the product?
  • What are the collection opportunities that I should expect within the collection window?

Analyses are executed asynchronously, and as a result of every request an analysis ID is returned. The API can be later polled with this ID to get the status and result of the analysis. Analyses results are typically ready after 20 to 60 seconds.

Analysis requests are ephemeral, and their result will be available for 24 hours only. Analysis requests have no cost and do not generate any tasking order submission.

Note: Collection times returned by the Analysis API are estimates and may shift slightly due to operational adjustments. For example, a satellite may be in maintenance at the time of execution, or updated orbital ephemerides may lead to changes in geometry and timing. When using analysis results to create a task, we recommend adding at least 10 minutes of buffer before and after the estimated collection windows.

Tasking API

The Tasking API provides endpoints for performing various task management operations, such as creation of tasks, retrieval of their status and collection progress and cancellation.

Please refer to the Tasking API Spec for full technical reference, and to Command line examples / Python examples sections to explore the wide range of operations that are allowed.