> 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-a-rental.md).

# Get a rental

GET /v1/rentals/{id}: the status and on-chain record of one rental.

Use this endpoint to poll a queued rental every 2 to 5 seconds until the status is `active`, and afterwards to read the on-chain record of the delegation and the reclaim.

## At a glance

| Item            | Detail                                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Method and path | `GET /v1/rentals/{id}`                                                                                                                    |
| 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) |

## Path parameters

| Name | Type   | Required | Default | Description                                                                                                                |
| ---- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes      | None    | The `rental_id` returned by [Create a rental](https://docs.luganodes.com/tron-energy/energy-rental-api/create-a-rental.md) |

## Sample request

Sample IDs, addresses and hashes are illustrative.

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

```bash
TIMESTAMP=$(date +%s)
RENTAL_ID="rnt_01J9X5..."
REQUEST_PATH="/v1/rentals/$RENTAL_ID"
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 %}

Replace `RENTAL_ID` with the `rental_id` from Create a rental. 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-a-rental.mjs" %}

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

const rentalId = "rnt_01J9X5...";
const { status, data } = await signedRequest("GET", `/v1/rentals/${rentalId}`);
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\_a\_rental.py" %}

```python
from tron_energy import signed_request

rental_id = "rnt_01J9X5..."
status, data = signed_request("GET", f"/v1/rentals/{rental_id}")
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
{
  "rental_id": "rnt_01J9X5...",
  "status": "reclaimed",
  "energy_delegated": 67500,
  "energy_used": 64285,
  "delegate_tx": "8f3c...",
  "reclaim_tx": "a91d...",
  "queued_at": "2026-10-19T10:00:00Z",
  "starts_at": "2026-10-19T10:00:31Z",
  "expires_at": "2026-10-19T10:00:41Z",
  "reclaimed_at": "2026-10-19T10:00:44Z",
  "failure_reason": null
}
```

{% endcode %}

A rental ID belonging to another client returns `404`.

## Response fields

| Field              | Type            | Description                                                                                                                                                   |
| ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rental_id`        | string          | Rental ID                                                                                                                                                     |
| `status`           | string          | `pending`, `active`, `reclaimed`, `failed` or `expired`. See [Rental lifecycle](https://docs.luganodes.com/tron-energy/energy-rental-api/rental-lifecycle.md) |
| `energy_delegated` | integer         | Energy delegated for this rental                                                                                                                              |
| `energy_used`      | integer or null | Energy the transaction consumed. Final once `reclaimed`                                                                                                       |
| `delegate_tx`      | string          | Hash of the delegation transaction                                                                                                                            |
| `reclaim_tx`       | string          | Hash of the reclaim transaction                                                                                                                               |
| `queued_at`        | string          | Time the rental joined the queue. Present only on queued rentals                                                                                              |
| `starts_at`        | string          | Start of the 10-second window                                                                                                                                 |
| `expires_at`       | string          | End of the 10-second window                                                                                                                                   |
| `reclaimed_at`     | string          | Time the energy was reclaimed                                                                                                                                 |
| `failure_reason`   | string or null  | Reason for a `failed` rental. `null` otherwise                                                                                                                |

While a rental is `pending`, each poll also returns `pending_reason` and a fresh `estimated_wait_seconds`. Both are described under [Create a rental](https://docs.luganodes.com/tron-energy/energy-rental-api/create-a-rental.md#response-fields).

## Errors

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

| HTTP | Code                  | When                                                             | Action                                  | Retry?                   |
| ---- | --------------------- | ---------------------------------------------------------------- | --------------------------------------- | ------------------------ |
| 401  | `UNAUTHORIZED`        | Invalid API key, signature or timestamp                          | Check your credentials and server clock | After a fix              |
| 404  | `NOT_FOUND`           | Unknown rental ID, or a rental ID that belongs to another client | Check the ID                            | No                       |
| 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` |
