> 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/list-rentals.md).

# List rentals

GET /v1/rentals: your rentals, newest first, for reconciliation.

Use this endpoint to reconcile transfers with delegations, or to find a rental when you do not have its ID.

## At a glance

| Item            | Detail                                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Method and path | `GET /v1/rentals`                                                                                                                         |
| 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                                                                            |
| ---------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------- |
| `status`   | string  | No       | None    | `pending`, `active`, `reclaimed`, `expired` or `failed`                                |
| `receiver` | string  | No       | None    | Filter by the receiver, the address that sends the transaction and receives the energy |
| `from`     | string  | No       | None    | Start of the date range. `from` and `to` are at most 31 days apart                     |
| `to`       | string  | No       | None    | End of the date range. `from` and `to` are at most 31 days apart                       |
| `limit`    | integer | No       | 50      | 1 to 100                                                                               |
| `cursor`   | string  | No       | None    | `next_cursor` from the previous page                                                   |

## Sample request

Sample IDs, addresses and hashes are illustrative.

{% tabs %}
{% tab title="cURL" %}
{% code title="list-rentals.sh" %}

```bash
TIMESTAMP=$(date +%s)
REQUEST_PATH="/v1/rentals?status=reclaimed&limit=50"
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="list-rentals.mjs" %}

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

const { status, data } = await signedRequest("GET", "/v1/rentals?status=reclaimed&limit=50");
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="list\_rentals.py" %}

```python
from tron_energy import signed_request

status, data = signed_request("GET", "/v1/rentals?status=reclaimed&limit=50")
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
{
  "data": [
    { "rental_id": "rnt_01J9X5...", "status": "reclaimed", "energy_used": 64285 }
  ],
  "next_cursor": "c_01JA..."
}
```

{% endcode %}

## Response fields

| Field                | Type            | Description                                                                                                                                                                      |
| -------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`               | array           | Rentals, newest first. Each item has the same fields as [Get a rental](https://docs.luganodes.com/tron-energy/energy-rental-api/get-a-rental.md); the sample shows three of them |
| `data[].rental_id`   | string          | Rental ID                                                                                                                                                                        |
| `data[].status`      | string          | Rental status. See [Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md)                                                              |
| `data[].energy_used` | integer or null | Energy the transaction consumed. Final once `reclaimed`                                                                                                                          |
| `next_cursor`        | string or null  | Cursor for the next page. `null` on the last page                                                                                                                                |

## Paging through results

Pass the `next_cursor` from one response as `cursor` on the next request, with the same filters. Stop when `next_cursor` is `null`.

## 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`     | A query parameter 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` |
