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

The whole flow is 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.0 }],
	"errors": [],
	"totalAud": 180.0,
	"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.

## Next steps

- [Ordering archive imagery](/api-reference/guides/ordering) — buy scenes already in the catalog.
- [Provenance & lineage](/api-reference/guides/provenance) — trace delivered captures back to their tasking order.
- [Billing & credits](/api-reference/guides/billing) — how credit reservations and enterprise invoices work.
