> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withleaf.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Tracking

> Track your Leaf API usage across field boundaries, machine file processing, field operations, and satellite imagery using contracts and consumption endpoints.

Leaf tracks data processing usage, not API access. You have unlimited API calls to retrieve processed data. Charges occur when Leaf successfully processes your data (pulls a file, creates a boundary, processes an image), not when you download or query results afterward.

## How usage tracking works

Usage is based on **spatially unique acres** processed per Leaf user. A few rules to keep in mind:

* The same geographic area processed under different Leaf users counts separately for each user.
* Repeated retrieval of the same processed data does not incur additional charges.
* If processing fails, the area is not counted.
* Deleted boundaries count toward usage for the current contract term only.

## What gets tracked

Each service tracks area with a specific product identifier:

| Product ID                   | What it tracks                                                                          |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `UNIFIED_AREA`               | Total unique area consumed across all services during the contract period               |
| `FIELDS_BOUNDARY`            | Field boundary area processed during the contract period                                |
| `AUDIT_FIELDS_BOUNDARY`      | Current total boundary area (not bounded by contract dates)                             |
| `OPERATIONS_FILE`            | Machine file area processed during the contract period                                  |
| `OPERATIONS_OPERATION`       | Field operation area (machine files intersecting boundaries) during the contract period |
| `SATELLITE_PROCESS_PLANET`   | Planet satellite imagery area processed during the contract period                      |
| `SATELLITE_PROCESS_SENTINEL` | Sentinel satellite imagery area processed during the contract period                    |

## Contracts

Contracts are automatically generated when you start using Leaf services. Each contract tracks usage for one product type with annual cycles. Use the contracts endpoints to find your contract IDs and check quota limits.

## Tracking usage

There are several ways to monitor consumption:

**API endpoints.** The billing endpoints give you programmatic access to usage data at both the API owner and individual Leaf user level.

**API owner level** shows spatially unique area across all your users (overlapping boundaries between users are deduplicated). This gives the overall footprint of your account.

**Leaf user level** shows each user's individual processing. These values may include spatial overlap between users, which is expected and reflects how billing is calculated.

The difference between the API owner total and the sum of all Leaf user totals indicates spatial overlap across your organization.

**Alerts.** Set up webhooks for events like `fieldBoundaryCreated`, `providerFileProcessingFinished`, and `operationProcessingFinished` to track processing as it happens.

**X-Total-Count header.** Most `GET All` endpoints include this header in the response, giving you a quick count of resources without paging through all results.

**CSM reports.** Your Customer Success Manager can provide usage and billing reports broken down by API owner and Leaf user.

## Endpoints

Base URL: `https://api.withleaf.io/services/billingapplication/api`

| Action                      | Method | Path                                                                 |
| --------------------------- | ------ | -------------------------------------------------------------------- |
| List contracts              | GET    | `/billing/contracts`                                                 |
| Get contract details        | GET    | `/billing/contracts/{contractId}`                                    |
| Get daily usage summary     | GET    | `/billing/contracts/{contractId}/consumption`                        |
| Get usage range (API owner) | GET    | `/billing/contracts/{contractId}/consumption/api-owner`              |
| Get usage range (Leaf user) | GET    | `/billing/contracts/{contractId}/consumption/leaf-user/{leafUserId}` |

The daily usage summary returns current-day data by default. Pass a `timestamp` parameter to get data for a specific day.

The range endpoints accept `startTime` and `endTime` parameters and return daily consumption breakdowns.

## Avoiding unexpected charges

* Assign provider credentials to one Leaf user per actual customer. Re-connecting the same data under multiple Leaf users counts each user's acreage separately.
* Use `customDataSync` and `organizationDataSync` to limit which fields and organizations Leaf processes.
* Create a separate API owner for test environments (e.g., `leaf-test@yourcompany.com`) to isolate test usage from production billing.

## What to do next

* [Billing API Reference](/api-reference/billing) for full endpoint details.
* [Configuration](/configuration/overview) for `customDataSync` and `organizationDataSync` to control data scope.
* [Alerts Overview](/alerts/overview) to set up usage monitoring webhooks.