Skip to content

Introduction

What is an order?

An order is Aleph's representation for a purchase request of a specific product, with all its required parameters.

As an evolution of our previous API ecosystem (Analysis API, Tasking API, Archive API, Delivery API), this new Aleph's API v2, a.k.a. "Orders API", represents a unified approach to satellite data procurement: the Orders API provides a single, comprehensive interface that spans the complete order lifecycle—from initial analysis and feasibility assessment, through order placement and tracking, to final delivery and consumption monitoring.

This unified design supports all products in our current offering (Archive, Standard Tasking, Rush Tasking, etc) while providing a scalable foundation for future data products and capabilities.

This document outlines the fundamental concepts, state models, and capabilities that define how orders work within the unified API framework.

Orders, contracts and products

Orders are always placed in the context of a Contract, which establishes purchase context, such as products that are available for ordering, default settings and possible variations for those products, and price for delivered quantities. In the context of an order, the product is specified by a unique SKU identifier, with each ID mapping to our products and their relevant variations where applicable.

Product Name Geometry sku Behaviors Controlled By contract_id
Standard Tasking Point TSKPOI-M Default footprint size, cloud cover threshold, and prioritization.
Standard Area Coverage Polygon TSKARE-M Cloud cover threshold and prioritization.
Rush Tasking Point TSKRSH-M.NN.NN Default footprint size, prioritization and optional processing levels.
Rush Tasking with Rapid Delivery Point TSKRRD-M.NN.NN Default footprint size, prioritization and optional processing levels.
Archive Imagery Polygon ARCIMG-M.NN.NN (None)
Legacy Archive Direct Download (*) Polygon ARCLGD-M.NN.NN Available processing levels.

(*) Legacy Archive Direct Download represents archive consumption performed through the legacy Archive API. This product appears in orders for tracking and consumption monitoring purposes only —it cannot be ordered through the Orders API. This legacy product will be phased out as users migrate to the Archive Imagery product.

Note: The setup of contracts with the appropriate defaults and optional parameters for each product is handled by Account Managers.

Order entities hierarchy

The Orders API manages three interconnected entities that represent the complete workflow from purchase request to final delivery:

  • Orders: The top-level entity representing your purchase request with all required parameters and conditions. Orders define what you want to acquire and under what specifications.

  • Captures: The source satellite imagery used to fulfill your order. For archive products, these captures already exist in our catalog and are immediately available for deliverable generation. For tasking products, captures follow a complete lifecycle before deliverables can be created.

  • Deliverables: The final products generated from captures and delivered to you as the output of your order. Deliverables are the actual goods you receive —processed imagery, analytics products, or other specified outputs that fulfill your order requirements. A single Capture may yield more than one Deliverable.

This hierarchy flows from order creation → capture collection or retrieval → deliverable generation, with each entity having its own state machine and lifecycle management within the unified API.

Orders

Order creation

For an order to be actually created in the system, the order request has to pass formal validations, namely: complies with request schema, all required paramenters are included, geometry type suits the product constraint, temporal and geometrical parameters within min/max constraints, etc. For full reference on required parameters and their supported ranges for each product, refer to our API Specs section.

Order states

Following is the Orders states diagram along with their descriptions.

Order States Diagram

  • Received: This is the initial state for an order upon creation. An assessment for the order is performed while in this state (physical and contractual restrictions).
  • In Progress: In this state, work is being done to generate deliverables.
  • Closed: No further activity is expected to happen for the order, be it due to order rejection, completion or cancellation.

As this representation is intentionally simple (few states) and general (agnostic of product being ordered) to support our diverse product portfolio, detailed tracking information is provided through the events system and the underlying Capture and Deliverable state machines, which offer granular visibility into the specific transitions that lead to order closure.

Order events

Event Description
OrderReceived Order created and ready for analysis
OrderCreatedFromTask Order created from external tasking system
OrderUpdatedFromTask Order updated from external tasking system
OrderAnalysisFailed Order analysis failed (order closed)
OrderAnalysisSucceeded Order analysis succeeded (order in progress)
OrderProcessingStarted Order processing initiated
OrderClosed Order closed successfully
OrderForceClosed Order force-closed administratively
OrderCancellationRequested Cancellation requested by user
OrderCancellationAccepted Cancellation accepted
OrderCancellationRejected Cancellation rejected
OrderClosingAttempt Attempt to close order (check if all deliverables completed)

Captures

Capture creation

When tasking new imagery, a Capture is created when our planning system effectively identifies and schedules a collection for the order.

When ordering a product based on an existing Capture (eg: Archived data), this states representation is not applicable.

Capture states

Capture States Diagram

  • Queued: This is the initial state for a capture upon creation. A capture in this state is scheduled for collection, with a defined date and time, satellite, geometrical characteristics, and unique capture_id.
  • Collecting: The collection is now in progress or imminent. While in this state, the satellite’s plan is locked with no further possible modifications before the collection time, i.e: it can no longer be re-scheduled by the system.
  • Acquired: Imagery was successfully collected, downloaded, ingested, and passed initial capture-level QC, making the raw data ready for deliverable processing.
  • Failed: Collection attempt was unsuccessful and cannot yield valid deliverables. Either of the steps failed: imaging, download, ingestion, capture-level QC.

Capture events

Event Description
CaptureScheduled Capture scheduled for acquisition
CaptureUnscheduled Capture cancelled/unscheduled
CaptureCollectionStarted Satellite collection started
CaptureCollectionFailed Satellite collection failed
CaptureQcFailed Capture quality control failed
CaptureAcquired Capture successfully acquired (triggers deliverable creation)

Deliverables

Deliverables creation

When tasking new imagery, a deliverable is created when the associated Capture reaches the Acquired state.

When ordering a product based on an existing Capture (eg: Archived data), a deliverable is created when the Order is feasible and transitions to state IN PROGRESS.

Deliverables states

Deliverable States Diagram

  • Processing: This is the initial state for a deliverable upon creation. Imagery is being processed, packaged to yield the required deliverable.
  • Delivered: Deliverable is ready for consumption on the Aleph platform.
  • Not Delivered: Deliverable is unavailable on the Aleph platform, typically due to generation failure or not meeting specifications.

Deliverables events

Event Description
DeliverableCreated Deliverable created for an order
ProcessingDeliverable Deliverable processing started
DeliverableDelivered Deliverable successfully delivered
DeliverableFailed Deliverable processing/delivery failed
DeliverableQcFailed Quality control failed
DeliverableQcSucceeded Quality control passed
DeliverableProcessingDelayed Triggered when a deliverable has been processing for a prolonged period
DeliverableRejectionRequested A user requested to reject the deliverable
DeliverableRejectionFailed The deliverable could not be rejected
DeliverableRejectionAccepted The deliverable rejection was accepted

Orders representation and parameters

Orders follow the GeoJSON specification standard for spatial data representation. An individual order is a GeoJSON Feature object, containing a geometry and properties, that include general order parameters (e.g., order name and SKU) and product-specific required and optional parameters (e.g., start, end, revisit_period for tasking products; outcome_id, processing_level for archive products).

When working with multiple orders, such as responses from list operations, they are represented as a GeoJSON FeatureCollection object—a collection of Feature objects (orders) as defined in the GeoJSON specification.

Orders currently support Point and Polygon geometries for our POI and AOI products. As our product offerings expand, the API will eventually support all standard GeoJSON geometry types (Point, MultiPoint, Polygon, MultiPolygon, LineString, MultiLineString).

💡Example of an order request's body:

{
  "type": "Feature", // Example of an archive order
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[10, 45], [11, 45], [11, 46], [10, 46], [10, 45]]]
  },
  "properties": {
    "order_name": "Single Polygon Archive Order",
    "sku": "ARCIMG-M.NN.NN",
    "parameters": {
      "processing_level": "L1C",
      "outcome_id": "38d53861-79b0-4281-9eaf-498511b6add1"
    }
  }
}

💡Example of the same order response body:

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[10, 45], [11, 45], [11, 46], [10, 46], [10, 45]]]
  },
  "properties": {
    "order_id": "000310",
    "contract_id": "cont.00000001-0000-0000-0000-000000000001",
    "contract_name": "My Contract",
    "project_id": null,
    "project_name": null,
    "sku": "ARCIMG-M.NN.NN",
    "product_name": "Archive",
    "order_name": "Single Polygon Archive Order",
    "parameters": {
      "processing_level": "L1C",
      "outcome_id": "38d53861-79b0-4281-9eaf-498511b6add1"
    },
    "status": "received",
    "created_at": "2025-01-01T10:00:00Z",
    "updated_at": "2025-01-01T10:05:00Z",
    "created_by": "user_id",
    "created_by_name": "John Doe",
    "latest_event": {
        // ...
    }
  }
}

💡Example resonse to a GET orders query, listing multiple orders as a FeatureCollection:

{
  "type": "FeatureCollection",
  "count": 4,
  "next": "https://api.satellogic.com/v2/orders?offset=20&limit=20",
  "previous": null,
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[10, 45], [11, 45], [11, 46], [10, 46], [10, 45]]]
      },
      "properties": {
        "order_id": "000311",
        "contract_id": "cont.00000001-0000-0000-0000-000000000001",
        "contract_name": "My Contract",
        "order_name": "Archive Order - Area 1",
        "sku": "ARCIMG-M.NN.NN",
        "parameters": {
            // ...
        },
        "status": "received",
        // ...
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [40, 15]
      },
      "properties": {
        "order_id": "000312",
        "contract_id": "cont.00000001-0000-0000-0000-000000000001",
        "contract_name": "My Contract",
        "order_name": "Standard Tasking Order - Daily",
        "sku": "TSKPOI-M.20.NN",
        "parameters": {
            // ...
        },
        "status": "closed",
        // ...
      }
    },
    ... // more orders
  ]
}

Orders API capabilities

Standards Compliance

  • STAC API: Archive search follows SpatioTemporal Asset Catalog specifications
  • GeoJSON: Spatial data representation using industry-standard formats
  • OAuth2: Enterprise authentication and authorization
  • REST: Resource-oriented design with predictable HTTP methods

User Profile & Contract Management

  • Access user profile information (name, email, role, permissions)
  • List available contracts and their associated product offerings
  • View contract-specific defaults and parameter constraints

Discovery & Feasibility Analysis

  • Archive Discovery: Browse existing satellite imagery collections using STAC-compliant search
  • Geospatial Search: Filter products by temporal, spatial, and specification criteria
  • Tasking Feasibility: Analyze POI collection opportunities with cloud cover forecasting (up to 7 days)

Order Management

  • Unified Ordering: Single interface for all product types (Archive, Standard Tasking, Rush Tasking)
  • Order Tracking: Real-time status updates through three-tier state machines (Order → Capture → Deliverable)
  • Event Monitoring: Granular event streams for detailed progress tracking and future notification capabilities.
  • Order Modification: Cancellation requests and administrative controls where applicable
  • Deliverable Access: Download processed imagery and analytics products

Consumption Monitoring

  • Accounting Reports: Detailed consumption reports for monitoring and billing