> For the complete documentation index, see [llms.txt](https://docs.luganodes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.luganodes.com/tron-energy/energy-rental-api/get-usage.md).

# Get usage

GET /v1/usage: daily rentals, activations and energy over a date range.

Use this endpoint to reconcile daily totals with your own records.

## At a glance

| Item            | Detail                                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Method and path | `GET /v1/usage`                                                                                                                           |
| Authentication  | Signed request. See [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md)             |
| Retry-safe      | Yes. The request only reads data                                                                                                          |
| Rate limit      | Per API key. See [Conventions and limits](https://docs.luganodes.com/tron-energy/energy-rental-api/conventions-and-limits.md#rate-limits) |

## Query parameters

| Name   | Type   | Required | Default | Description            |
| ------ | ------ | -------- | ------- | ---------------------- |
| `from` | string | Yes      | None    | Start date, YYYY-MM-DD |
| `to`   | string | Yes      | None    | End date, YYYY-MM-DD   |

## Sample request

Sample values are illustrative.

{% tabs %}
{% tab title="cURL" %}
{% code title="get-usage.sh" %}

```bash
TIMESTAMP=$(date +%s)
REQUEST_PATH="/v1/usage?from=2026-10-01&to=2026-10-31"
BODY=""
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "GET" "$REQUEST_PATH" "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.* //')
curl -X GET "$BASE_URL$REQUEST_PATH" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE"
```

{% endcode %}

The path includes the query string, and the signature covers it. The request is signed inline and needs `BASE_URL`, `API_KEY` and `API_SECRET` in your environment.
{% endtab %}

{% tab title="Node.js" %}
{% code title="get-usage.mjs" %}

```javascript
import { signedRequest } from "./tron_energy.mjs";

const { status, data } = await signedRequest("GET", "/v1/usage?from=2026-10-01&to=2026-10-31");
console.log(status, data);
```

{% endcode %}

`signedRequest` is the helper from [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md), saved as `tron_energy.mjs`.
{% endtab %}

{% tab title="Python" %}
{% code title="get\_usage.py" %}

```python
from tron_energy import signed_request

status, data = signed_request("GET", "/v1/usage?from=2026-10-01&to=2026-10-31")
print(status, data)
```

{% endcode %}

`signed_request` is the helper from [Authentication and signing](https://docs.luganodes.com/tron-energy/energy-rental-api/making-requests.md), saved as `tron_energy.py`.
{% endtab %}
{% endtabs %}

## Responses

{% code title="200 OK" %}

```json
{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "days": [
    {
      "date": "2026-10-01",
      "rentals": 1240,
      "rentals_queued": 85,
      "rentals_failed": 3,
      "rentals_expired": 2,
      "activations": 5,
      "energy_delegated": 84320000,
      "energy_used": 80115000
    }
  ]
}
```

{% endcode %}

## Response fields

| Field                     | Type    | Description                      |
| ------------------------- | ------- | -------------------------------- |
| `from`                    | string  | Start of the range               |
| `to`                      | string  | End of the range                 |
| `days`                    | array   | One entry per day with rentals   |
| `days[].date`             | string  | Day in UTC                       |
| `days[].rentals`          | integer | Rentals that became active       |
| `days[].rentals_queued`   | integer | Rentals that waited in the queue |
| `days[].rentals_failed`   | integer | Rentals that ended `failed`      |
| `days[].rentals_expired`  | integer | Rentals that ended `expired`     |
| `days[].activations`      | integer | Addresses activated              |
| `days[].energy_delegated` | integer | Total energy delegated           |
| `days[].energy_used`      | integer | Total energy consumed            |

## Errors

The full list is in [Errors](https://docs.luganodes.com/tron-energy/energy-rental-api/errors.md).

| HTTP | Code                  | When                                            | Action                                  | Retry?                   |
| ---- | --------------------- | ----------------------------------------------- | --------------------------------------- | ------------------------ |
| 400  | `INVALID_REQUEST`     | `from` or `to` is missing or has the wrong type | Fix the request                         | No                       |
| 401  | `UNAUTHORIZED`        | Invalid API key, signature or timestamp         | Check your credentials and server clock | After a fix              |
| 429  | `RATE_LIMITED`        | Too many requests                               | Retry after `Retry-After`               | Yes, after `Retry-After` |
| 503  | `SERVICE_UNAVAILABLE` | Planned maintenance or an outage                | Retry after `Retry-After`               | Yes, after `Retry-After` |

## Related

* [Get a rental](https://docs.luganodes.com/tron-energy/energy-rental-api/get-a-rental.md): the status and on-chain record of one rental.
* [Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md): what `queued`, `failed` and `expired` mean.
