Tasking new acquisitions

Tasking orders a new acquisition — you ask a provider to collect imagery over your area of interest in a future window, rather than buying something already in the archive. Because a new collection has to be assessed, tasking can run through a feasibility study and/or a quotation before it becomes a firm, priced order.

Geopera makes the whole journey server-authoritative: the price you accept is the price the backend computes, and accepting a priced option is a single step that reserves credits (or accrues to an enterprise invoice).

1. Check feasibility

Before committing, ask whether a request over your AOI is likely to need a feasibility study. This is a read — it predicts per-feature, nothing is created.

curl -s -X POST https://api.geopera.com/v1/op/orders.tasking.feasibility_check \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dataProduct": "the-product-id",
    "displayName": "Harbour monitoring",
    "featureCollection": {
      "type": "FeatureCollection",
      "features": [
        { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [ ... ] }, "properties": {} }
      ]
    },
    "params": { "...": "product-specific tasking parameters" }
  }'

The product-specific params (acquisition window, max cloud cover, off-nadir limits, priority…) describe the collection you want.

2. Preview the price

orders.tasking.estimate returns the server-authoritative price for one or many AOI groups. Each group is one AOI plus its tasking parameters.

curl -s -X POST https://api.geopera.com/v1/op/orders.tasking.estimate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groups": [
      {
        "dataProduct": "the-product-id",
        "featureCollection": { "type": "FeatureCollection", "features": [ ... ] },
        "params": { "...": "tasking params" }
      }
    ]
  }'

{
  "groups": [ { "aoi_km2": 50.0, "credits": 18000, "aud": 180.00 } ],
  "errors": [],
  "totalAud": 180.00,
  "totalCredits": 18000
}

As with archive estimates, errors flags any AOI that couldn’t be priced so you can fix the request before placing it.

3. Place the tasking order

orders.tasking.place creates one order spanning one or many AOI groups. It is an external_spend operation and accepts an Idempotency-Key. Depending on the product, the order may be immediately reserved, or it may enter a feasibility / quotation state (subStatus) awaiting your decision.

curl -s -X POST https://api.geopera.com/v1/op/orders.tasking.place \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c4a...-unique-per-order" \
  -d '{
    "projectId": "your-project-id",
    "displayName": "Harbour monitoring Q3",
    "groups": [
      {
        "dataProduct": "the-product-id",
        "featureCollection": { "type": "FeatureCollection", "features": [ ... ] },
        "params": { "...": "tasking params" }
      }
    ]
  }'

{
  "id": "a91c...",
  "status": "pending",
  "subStatus": "awaiting_feasibility",
  "orderType": "tasking",
  "billingMode": "credit",
  "currency": "AUD",
  "totalAud": 0.0,
  "estimatedCredits": 18000,
  "groups": [ { "...": "the AOI groups, as placed" } ]
}

One order can carry many AOIs (order_tasking_groups), so you don’t place a separate order per polygon. estimatedCredits reflects the priced estimate; the firm charge happens when you accept.

4. Accept a feasibility option

When a study completes, it offers one or more priced options (different acquisition windows, look angles, etc.). Accepting one is a single, server-priced step that reserves credits (or accrues to the enterprise invoice):

curl -s -X POST https://api.geopera.com/v1/op/orders.tasking.feasibility_decide \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "study_id": "study-uuid",
    "acceptedOptionId": "option-uuid"
  }'

List outstanding studies with orders.tasking.feasibility_studies.list (filter by workspaceId, orderId, or decision).

5. Accept or reject a quotation

For products that return a formal quotation, decide on it directly. Accepting reserves credits; rejecting closes it out with no charge:

curl -s -X POST https://api.geopera.com/v1/op/orders.tasking.quotation_decide \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "quotation_id": "quote-uuid", "decision": "ACCEPTED" }'

decision is ACCEPTED or REJECTED. List open quotations with orders.tasking.quotations.list.

6. Track coverage

Once a tasking order is collecting, orders.coverage.get reports how much of each AOI has been satisfied, and orders.coverage.groups.list breaks it down per group. Delivered captures arrive as STAC items in your project, each with a provenance edge back to the tasking order.

Billing fork

Tasking honours the same billing modes as archive orders: a credit org reserves credits on accept; an enterprise org accrues the amount to its monthly invoice. The billingMode field tells you which path applied. See Billing & credits.

Resource-style route

The tasking capability is also exposed on POST /v2/tasking/... routes for STAC/UP42 style clients — same operations, same scopes, same provenance.