> ## 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 Monitoring endpoints

> Monitor your usage with contracts and consumption endpoints.

All HTTP methods should be prepended by this service's endpoint:

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

## Usage Monitoring Endpoints

Monitor your usage with these endpoints:

| Description                           | Endpoints                                                                   |
| ------------------------------------- | --------------------------------------------------------------------------- |
| List your contracts                   | `GET /billing/contracts`                                                    |
| Get contract details                  | `GET /billing/contracts/{contract_id}`                                      |
| Get daily usage summary               | `GET /billing/contracts/{contract_id}/consumption`                          |
| Get usage range for your organization | `GET /billing/contracts/{contract_id}/consumption/api-owner`                |
| Get usage range for specific user     | `GET /billing/contracts/{contract_id}/consumption/leaf-user/{leaf_user_id}` |

***

## List your contracts

<span style={{color: 'green', fontWeight: 'bold'}}>GET</span> `/billing/contracts`

Get a list of all usage monitoring contracts available for your organization. Each contract represents a different service or feature you can monitor.

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/billingapplication/api/billing/contracts'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  response = requests.get(endpoint, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  axios.get(endpoint, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)
  ```
</CodeGroup>

### Response

```json theme={null}
[
  {
    "id": "unique id",
    "product": "FIELDS_BOUNDARY",
    "startDate": "2023-01-01T00:00:00Z",
    "endDate": "2024-01-01T00:00:00Z",
    "region": null
  }
]
```

**Response fields:**

* `id`: Unique identifier for this contract
* `product`: Which service this tracks
* `startDate`: When usage monitoring began for this contract
* `endDate`: When usage monitoring ends for this contract
* `region`: Geographic region, if applicable

***

## Get contract details

<span style={{color: 'green', fontWeight: 'bold'}}>GET</span> `/billing/contracts/{contract_id}`

Get detailed information about a specific usage monitoring contract.

### Parameters

| Parameter     | Type | Description          |
| ------------- | ---- | -------------------- |
| `contract_id` | path | UUID of the contract |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  response = requests.get(endpoint, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  axios.get(endpoint, { headers })
    .then(res => console.log(res.data))
    .catch(console.error)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "unique id",
  "product": "FIELDS_BOUNDARY",
  "startDate": "2023-01-01T00:00:00Z",
  "endDate": "2024-01-01T00:00:00Z",
  "region": null
}
```

***

## Get daily usage summary

<span style={{color: 'green', fontWeight: 'bold'}}>GET</span> `/billing/contracts/{contract_id}/consumption`

Get usage metrics for a specific contract for a single day. If you don't specify a date, it returns today's usage.

### Parameters

| Parameter     | Type             | Description                                                    |
| ------------- | ---------------- | -------------------------------------------------------------- |
| `contract_id` | path             | UUID of the contract                                           |
| `timestamp`   | query (optional) | Date to get usage for in ISO format `YYYY-MM-DDTHH:MM:SS.sssZ` |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption?timestamp=2024-01-15T00:00:00.000Z'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  response = requests.get(endpoint, headers=headers, params={
      'timestamp': '2024-01-15T00:00:00.000Z'
  })
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  axios.get(endpoint, { headers, params: { timestamp: '2024-01-15T00:00:00.000Z' } })
    .then(res => console.log(res.data))
    .catch(console.error)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "areaUnit": "Acre",
  "date": "2024-01-15T00:00:00Z",
  "totalUniqueArea": 0.8,
  "leafUsersAreas": [
    {
      "leafUserId": "uuid1",
      "totalArea": 0.6
    },
    {
      "leafUserId": "uuid2",
      "totalArea": 0.4
    }
  ]
}
```

**Response fields:**

* `areaUnit`: Unit of measurement, `Acre` or `Hectare`
* `date`: The date this usage data represents
* `totalUniqueArea`: Total unique area processed, removing overlaps between users
* `leafUsersAreas`: Breakdown of usage by individual users

***

## Get usage range for your organization

<span style={{color: 'green', fontWeight: 'bold'}}>GET</span> `/billing/contracts/{contract_id}/consumption/api-owner`

Get usage metrics for your entire organization over a date range. Shows daily breakdown of total and cumulative usage.

### Parameters

| Parameter     | Type  | Description                                         |
| ------------- | ----- | --------------------------------------------------- |
| `contract_id` | path  | UUID of the contract                                |
| `startTime`   | query | Start date in ISO format `YYYY-MM-DDTHH:MM:SS.sssZ` |
| `endTime`     | query | End date in ISO format `YYYY-MM-DDTHH:MM:SS.sssZ`   |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption/api-owner?startTime=2024-01-01T00:00:00.000Z&endTime=2024-01-31T00:00:00.000Z'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption/api-owner'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  response = requests.get(endpoint, headers=headers, params={
      'startTime': '2024-01-01T00:00:00.000Z',
      'endTime': '2024-01-31T00:00:00.000Z'
  })
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption/api-owner'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  axios.get(endpoint, {
    headers,
    params: {
      startTime: '2024-01-01T00:00:00.000Z',
      endTime: '2024-01-31T00:00:00.000Z'
    }
  })
    .then(res => console.log(res.data))
    .catch(console.error)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "areaUnit": "Acre",
  "areaPerDay": [
    {
      "date": "2024-01-02T00:00:00Z",
      "totalArea": 90.0,
      "dailyArea": 65.0
    },
    {
      "date": "2024-01-03T00:00:00Z",
      "totalArea": 90.0,
      "dailyArea": 0.0
    }
  ]
}
```

**Response fields:**

* `areaUnit`: Unit of measurement, `Acre` or `Hectare`
* `areaPerDay`: Array of daily usage data
* `date`: The date for this data point
* `totalArea`: Cumulative area processed up to this date
* `dailyArea`: New area processed on this specific date

***

## Get usage range for specific user

<span style={{color: 'green', fontWeight: 'bold'}}>GET</span> `/billing/contracts/{contract_id}/consumption/leaf-user/{leaf_user_id}`

Get usage metrics for a specific Leaf user over a date range. Shows how much area this user has processed day by day.

### Parameters

| Parameter      | Type  | Description                                         |
| -------------- | ----- | --------------------------------------------------- |
| `contract_id`  | path  | UUID of the contract                                |
| `leaf_user_id` | path  | UUID of the Leaf user                               |
| `startTime`    | query | Start date in ISO format `YYYY-MM-DDTHH:MM:SS.sssZ` |
| `endTime`      | query | End date in ISO format `YYYY-MM-DDTHH:MM:SS.sssZ`   |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption/leaf-user/{leaf_user_id}?startTime=2024-01-01T00:00:00.000Z&endTime=2024-01-31T00:00:00.000Z'
  ```

  ```python Python theme={null}
  import requests

  TOKEN = 'YOUR_TOKEN'
  endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption/leaf-user/{leaf_user_id}'
  headers = {'Authorization': f'Bearer {TOKEN}'}

  response = requests.get(endpoint, headers=headers, params={
      'startTime': '2024-01-01T00:00:00.000Z',
      'endTime': '2024-01-31T00:00:00.000Z'
  })
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios')
  const TOKEN = 'YOUR_TOKEN'

  const endpoint = 'https://api.withleaf.io/services/billingapplication/api/billing/contracts/{contract_id}/consumption/leaf-user/{leaf_user_id}'
  const headers = { 'Authorization': `Bearer ${TOKEN}` }

  axios.get(endpoint, {
    headers,
    params: {
      startTime: '2024-01-01T00:00:00.000Z',
      endTime: '2024-01-31T00:00:00.000Z'
    }
  })
    .then(res => console.log(res.data))
    .catch(console.error)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "areaUnit": "Acre",
  "areaPerDay": [
    {
      "date": "2024-01-02T00:00:00Z",
      "totalArea": 0.6,
      "dailyArea": 0.6
    },
    {
      "date": "2024-01-03T00:00:00Z",
      "totalArea": 0.6,
      "dailyArea": 0.0
    }
  ]
}
```

**Response fields:**

* `areaUnit`: Unit of measurement, `Acre` or `Hectare`
* `areaPerDay`: Array of daily usage data for this user
* `date`: The date for this data point
* `totalArea`: Cumulative area processed by this user up to this date
* `dailyArea`: New area processed by this user on this specific date