Track and Manage Tasking Orders

Once you have placed a tasking order, there are a number of endpoints that will enable you to track, modify or cancel your order. This page covers managing both individual tasking orders and recurring order series.

Managing individual orders

This section outlines how to track and manage one off tasking orders

Tracking orders

You can use the "Retrieve a tasking order" endpoint to get information about a specific tasking order:

export ORDER_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
curl -X GET "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/${ORDER_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

The response returns a Feature, which also includes the current status of the Order along with a full breakdown of the status history in the status_history field

{
    "type": "Feature",
    "geometry": {
        "bbox": [
            ...
        ],
        "type": "Point",
        "coordinates": [
            ...
        ]
    },
    "properties": {
        "stac:item_id": "string",
        "stac:datetime": "...",
        "stac:metadata": {
            ...
        },
        "licence_level": "My Licence",
        "addon:withhold": "PT0H",
        "name": "My Order",
        "product": "standard",
        "datetime": ".../...",
        "satvu:day_night_mode": "day",
        "max_cloud_cover": 15,
        "min_off_nadir": 0,
        "max_off_nadir": 30,
        "status": "fulfilled",
        "created_at": "...",
        "updated_at": "...",
        "status_history": [
            {
                "status_from": "in progress",
                "status_to": "fulfilled",
                "datetime_updated": "...",
                "reason": "Image delivered to customer - order fulfilled"
            },
            {
                "status_from": "staged",
                "status_to": "committed",
                "datetime_updated": "...",
                "reason": "Satellite task assigned"
            },
            {
                "status_from": None,
                "status_to": "staged",
                "datetime_updated": "...",
                "reason": "Order created"
            }
        ]
    },
    "id": "...",
    "links": [
        ...
    ],
    "contract_id": "...",
    "price": {
        ...
    }
}

You can also view all your tasking orders with "List all tasking orders" endpoint:

curl -X GET "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Searching orders

The order search endpoint provides more advanced parameters to search your existing orders. The following example searches orders that are placed in the specified geometry:

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/search/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "collections": [
    "orders"
  ],
  "intersects": {
    "coordinates": [
      [
        [
          -8.60621344099522,
          60.63920763634644
        ],
        [
          -14.213293594801314,
          45.95851155946286
        ],
        [
          10.621928171802324,
          52.72769978027327
        ],
        [
          -8.60621344099522,
          60.63920763634644
        ]
      ]
    ],
    "type": "Polygon"
  }
}'

View individual tasks assigned to an order

For standard tasking orders, it may require more than one task attempt to fulfil an order. The tasks endpoint provides a list of all of the tasks that have been assigned to a specific order along with the current status of each task, and the full status history.

export ORDER_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
curl -X GET "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/${ORDER_ID}/tasks" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

An example response is shown below. The details field within the status_history provides more detail on what triggered the change in status. For example if a task did not fulfil an order due to the cloud cover of the captured image being greater than the parameters defined in the standard tasking order.

{
    "order_id": "...",
    "tasks": [
        {
            "id": "...",
            "status": "planned",
            "created_at": "...",
            "updated_at": "...",
            "acquisition": {
                ...
            },
            "status_history": [
                {
                    "status_from": "processing",
                    "status_to": "fulfilled",
                    "datetime_updated": "...",
                    "reason": "Task fulfilled",
                    "details": None
                },
                {
                    "status_from": "in progress",
                    "status_to": "processing",
                    "datetime_updated": "...",
                    "reason": "Task processing",
                    "details": None
                },
                {
                    "status_from": None,
                    "status_to": "in progress",
                    "datetime_updated": "...",
                    "reason": "Satellite task assigned",
                    "details": None
                }
            ]
        }
    ]
}

Modifying an order

Various aspects of a tasking order can be modified after the point at which the order has been placed. The point at which the fields can be modified depend on the status of the order:

• Order name can be modified at any point.
• Order properties that impact the price of an order (withhold and licence level) can be modified in thestaged or in progress statuses.
• For Standard tasking orders, tasking parameters (geometry, tasking window, day/night, cloud cover and off nadir angle) can only be modified in the staged status.
• For Assured tasking orders, tasking parameters cannot be modified. To modify an assured order, we recommend that you cancel the order and place a new assured order.

All of the order fields can be modified using the 'Edit tasking order' endpoint

curl -X PATCH "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/${ORDER_ID}/" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
    "geometry": {
      "type": "Point",
      "coordinates": [..,..]
      },
    "properties": {
      "licence_level": "My Licence",
      "addon:withhold": "PT0H",
      "name": "My Order",
      "start_time": "2026-01-01T00:00:00+00:00",
      "end_time": "2026-01-30T00:00:00+00:00",
      "satvu:day_night_mode": "day",
      "max_cloud_cover": 100,
      "min_off_nadir": 0,
      "max_off_nadir": 45
      }
    }'

There are also endpoints to run feasibility and get a price estimate for an order modification prior to making the updates. Further information on these endpoints can be found in the full Tasking API specification

Cancelling an order

Tasking orders in the staged status can be cancelled free of charge. Once an order has been added to the satellite tasking plan, the order moves to the in progress status and the order can no longer be cancelled.

For orders in the staged status, the Order cancellation endpoint can be used to cancel the order via the API

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/orders/${ORDER_ID}/cancel" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

Managing a recurring series

For recurring order series, modifications and cancellations apply to future child orders only — any orders that have already been created within the series are not affected. For information on creating a recurring series, see the Recurring Series Tasking Tutorial.

Modifying a series

The name of a series can be updated at any time. All other fields (geometry, order_parameters, frequency, total_order_count or end_date) can be modified while the series status is in progress.

export SERIES_ID="xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
curl -X PATCH "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/series/${SERIES_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
  "name": "Monthly monitoring - Manchester (updated)",
  "total_order_count": 12
}'

info

If you update total_order_count alongside other parameters such as frequency, ensure the new value accounts for any orders already created in the series.

Cancelling a series

To cancel a series and prevent any further child orders from being created, use the series cancellation endpoint:

curl -X POST "https://api.satellitevu.com/otm/v2/${CONTRACT_ID}/tasking/series/${SERIES_ID}/cancel" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

A successful cancellation returns a 204 response with no body. Any reserved credit for unfulfilled future orders is returned to your credit limit. Orders that have already been fulfilled are not affected.