<!-- Source: https://docs.geopera.com/api-reference/guides/tasking · Markdown for LLMs -->

# 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).

| Step | Operation | Side-effect | Scope |
|---|---|---|---|
| Will this need a study? | `orders.tasking.feasibility_check` | read | `orders:read` |
| Preview AOI price | `orders.tasking.estimate` | read | `orders:read` |
| Place / request | `orders.tasking.place` | spend | `orders:write` |
| Accept a feasibility option | `orders.tasking.feasibility_decide` | spend | `orders:write` |
| Accept / reject a quotation | `orders.tasking.quotation_decide` | spend | `orders:write` |
| List studies / quotations | `orders.tasking.feasibility_studies.list` / `…quotations.list` | read | `orders:read` |
| Coverage of a placed order | `orders.coverage.get` | read | `orders:read` |

## 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.

```bash
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.

```bash
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" }
      }
    ]
  }'
```

```json
{
  "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.

```bash
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" }
      }
    ]
  }'
```

```json
{
  "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):

```bash
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:

```bash
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](/api-reference/guides/billing).

## 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.