# Tron events server

**Base URL:** `https://mainnet.tron.tronql.com`

***

## Table of Contents

* [Authentication](#authentication)
* [Concepts](#concepts)
* [Transactions](#transactions)
* [Transfers](#transfers)
* [Events](#events)
* [Blocks](#blocks)
* [Contract Logs](#contract-logs)
* [Contract Events (ABI-decoded)](#contract-events-abi-decoded)
* [TronGrid-Compatible Events](#trongrid-compatible-events)
* [TRC20](#trc20)

***

## Authentication

Two methods are supported:

**Header (recommended):**

```
GET https://mainnet.tron.tronql.com/transactions
Authorization: <your-token>
```

**Token in subdomain:**

```
GET https://<your-token>.mainnet.tron.tronql.com/transactions
```

***

## Concepts

### Pagination

Most list endpoints use 1-based page numbers (`start=1` is the first page). **Contract Logs** and **Contract Events** endpoints are 0-based (`start=0`).

| Parameter | Description              | Default |
| --------- | ------------------------ | ------- |
| `limit`   | Number of items per page | 25      |
| `start`   | Page number              | 1 or 0  |

### Sorting

Pass a field name to `sort`. Prefix with `-` for descending order.

**Supported sort fields for events, transactions, transfers:**

| `sort` value       | Sorts by                 |
| ------------------ | ------------------------ |
| `timeStamp`        | Timestamp ascending      |
| `-timeStamp`       | Timestamp descending     |
| `blockNumber`      | Block number ascending   |
| `-blockNumber`     | Block number descending  |
| `transactionId`    | Transaction ID ascending |
| `energyUsageTotal` | Energy usage ascending   |
| `netFee`           | Net fee ascending        |

**Supported sort fields for blocks:**

| `sort` value      | Sorts by                    |
| ----------------- | --------------------------- |
| `timeStamp`       | Timestamp ascending         |
| `-timeStamp`      | Timestamp descending        |
| `blockNumber`     | Block number ascending      |
| `blockHash`       | Block hash ascending        |
| `transactionSize` | Transaction count ascending |

### Timestamps

All timestamps (`since`, `fromTimestamp`) are Unix milliseconds (e.g., `1620000000000`).

### Solidified Blocks

A *solidified* (confirmed) block has received enough network confirmations and cannot be rolled back. The `latestSolidifiedBlockNumber` value is returned on most responses. Events in blocks above this number are marked `_unconfirmed: true` in TronGrid-compatible responses.

***

## Transactions

### List Transactions

**GET** `/transactions`

**Query Parameters:**

| Name       | Type   | Description           | Default    |
| ---------- | ------ | --------------------- | ---------- |
| `limit`    | int    | Page size (max 100)   | 25         |
| `sort`     | string | Sort field            | -timeStamp |
| `start`    | int    | Page number (1-based) | 1          |
| `block`    | int    | Minimum block number  | 0          |
| `block_to` | int    | Maximum block number  | —          |

**Response:**

```json
{
  "total": 1234567,
  "data": [
    {
      "transactionId": "9a4f09...",
      "blockHash": "00000000...",
      "blockNumber": 4835773,
      "energyUsage": 0,
      "energyFee": 0,
      "originEnergyUsage": 0,
      "energyUsageTotal": 13000,
      "netUsage": 267,
      "netFee": 0,
      "result": "SUCCESS",
      "contractAddress": "TR7NHq...",
      "contractType": "TriggerSmartContract",
      "feeLimit": 100000000,
      "contractCallValue": 0,
      "timeStamp": 1620000000000,
      "triggerName": "triggerSmartContract",
      "internalTrananctionList": null,
      "fromAddress": "TJ7yJN...",
      "toAddress": "TAEcoD...",
      "assetName": "",
      "assetAmount": 0,
      "contractResult": "0x",
      "latestSolidifiedBlockNumber": 4835755,
      "data": ""
    }
  ]
}
```

**Example:** `https://mainnet.tron.tronql.com/transactions?limit=25&sort=-timeStamp&block=10000&block_to=20000`

***

### Get Transaction by Hash

**GET** `/transactions/{hash}`

**Response:** `{ "transaction": { ...TransactionItem } }`

**Example:** `https://mainnet.tron.tronql.com/transactions/9a4f096700672d7420889cd76570ea47bfe9ef815bb2137b0d4c71b3d23309e9`

***

### Get Transactions Total

**GET** `/transactions/total`

Returns total transaction count as plain text.

**Example:** `https://mainnet.tron.tronql.com/transactions/total` → `1234567`

***

## Transfers

Transfers are transactions of type `TransferContract` or `TransferAssetContract`.

### List Transfers

**GET** `/transfers`

**Query Parameters:**

| Name    | Type   | Description                        | Default    |
| ------- | ------ | ---------------------------------- | ---------- |
| `limit` | int    | Page size (max 100)                | 25         |
| `sort`  | string | Sort field                         | -timeStamp |
| `start` | int    | Page number (1-based)              | 1          |
| `from`  | string | Filter by sender address           | —          |
| `to`    | string | Filter by recipient address        | —          |
| `token` | string | Filter by token name (e.g., `trx`) | —          |
| `block` | int    | Minimum block number               | —          |

**Response:**

```json
{
  "total": 56789,
  "data": [ ...TransactionItem ]
}
```

**Example:** `https://mainnet.tron.tronql.com/transfers?token=trx&from=TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt`

***

### Get Transfer by Hash

**GET** `/transfers/{hash}`

Returns 404 if the transaction exists but is not a transfer type.

**Response:** `{ "transaction": { ...TransactionItem } }`

**Example:** `https://mainnet.tron.tronql.com/transfers/70d655a17e04d6b6b7ee5d53e7f37655974f4e71b0edd6bcb311915a151a4700`

***

### Get Transfers Total

**GET** `/transfers/total`

Returns total transfer count as plain text.

**Example:** `https://mainnet.tron.tronql.com/transfers/total` → `56789`

***

### Get Transfers Total by Address

**GET** `/transfers/total/{address}`

Returns total transfer count for a specific address as plain text.

**Example:** `https://mainnet.tron.tronql.com/transfers/total/TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt` → `42`

***

## Events

Events are smart contract logs indexed by the indexer. These endpoints return a **native TronQL format** (see also [TronGrid-Compatible Events](#trongrid-compatible-events) for TronGrid format).

### Event Object

```json
{
  "eventSignature": "Transfer(address,address,uint256)",
  "eventSignatureFull": "Transfer(address _from, address _to, uint256 value)",
  "eventName": "Transfer",
  "topicMap": { "_from": "TJ7yJN...", "_to": "TAEcoD..." },
  "dataMap": { "value": "1000000" },
  "transactionId": "9a4f09...",
  "contractAddress": "TR7NHq...",
  "callerAddress": "TJ7yJN...",
  "originAddress": "TJ7yJN...",
  "creatorAddress": "TR7NHq...",
  "blockNumber": 4835773,
  "timeStamp": 1620000000000,
  "triggerName": "triggerSmartContract",
  "uniqueId": "9a4f09..._0",
  "removed": "false",
  "latestSolidifiedBlockNumber": 4835755,
  "abiString": null,
  "rawData": {}
}
```

> `uniqueId` is `{transactionHash}_{eventIndex}`, e.g., `9a4f09..._0`.

***

### List Events

**GET** `/events`

**Query Parameters:**

| Name         | Type   | Description           | Default    |
| ------------ | ------ | --------------------- | ---------- |
| `limit`      | int    | Page size (max 100)   | 25         |
| `sort`       | string | Sort field            | -timeStamp |
| `start`      | int    | Page number (1-based) | 1          |
| `block`      | int    | Minimum block number  | 0          |
| `event_name` | string | Filter by event name  | —          |

**Response:** Plain JSON array of Event objects (no `total` wrapper).

**Example:** `https://mainnet.tron.tronql.com/events?limit=25&sort=-timeStamp&block=10000`

***

### Get Events Total

**GET** `/events/total`

Returns total event count as plain text.

**Example:** `https://mainnet.tron.tronql.com/events/total` → `98765432`

***

### Get Event by Unique ID

**GET** `/events/uniqueId/{uniqueId}`

Returns a single event. Returns 404 if not found.

**Example:** `https://mainnet.tron.tronql.com/events/uniqueId/9a4f096700672d7420889cd76570ea47bfe9ef815bb2137b0d4c71b3d23309e9_0`

***

### Get Events by Transaction

**GET** `/events/transaction/{transactionId}`

Returns all events emitted by a transaction.

**Example:** `https://mainnet.tron.tronql.com/events/transaction/cd402e64cad7e69c086649401f6427f5852239f41f51a100abfc7beaa8aa0f9c`

***

### Get Confirmed Events

**GET** `/events/confirmed`

Returns only events from solidified (confirmed) blocks. Same query parameters as [`/events`](#list-events).

**Example:** `https://mainnet.tron.tronql.com/events/confirmed?since=1620000000000&limit=25`

***

### Get Events by Timestamp

**GET** `/events/timestamp`

Same as `/events` but additionally supports filtering by `contract` address. Uses `block` as the minimum block number filter (not a timestamp filter despite the endpoint name).

| Name         | Type   | Description                | Default    |
| ------------ | ------ | -------------------------- | ---------- |
| `limit`      | int    | Page size (max 100)        | 25         |
| `sort`       | string | Sort field                 | -timeStamp |
| `start`      | int    | Page number (1-based)      | 1          |
| `block`      | int    | Minimum block number       | 0          |
| `event_name` | string | Filter by event name       | —          |
| `contract`   | string | Filter by contract address | —          |

**Example:** `https://mainnet.tron.tronql.com/events/timestamp?block=1620000&contract=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t&limit=25`

***

### Get Events by Contract Address

**GET** `/events/{contractAddress}`

Returns events emitted by a specific contract. Response items are flattened: `topicMap` and `dataMap` fields are merged into the top-level object alongside standard fields.

**Query Parameters:**

| Name         | Type   | Description            | Default    |
| ------------ | ------ | ---------------------- | ---------- |
| `limit`      | int    | Page size (max 100)    | 25         |
| `sort`       | string | Sort field             | -timeStamp |
| `start`      | int    | Page number (1-based)  | 1          |
| `block`      | int    | Minimum block number   | 0          |
| `since`      | int    | Minimum timestamp (ms) | 0          |
| `event_name` | string | Filter by event name   | —          |

**Example:** `https://mainnet.tron.tronql.com/events/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk?event_name=Bet&limit=25`

***

### Get Events by Contract Address and Event Name

**GET** `/events/contract/{contractAddress}/{eventName}`

Accepts the same query parameters as `/events`.

**Example:** `https://mainnet.tron.tronql.com/events/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet?limit=25&sort=-timeStamp`

***

### Get Events by Contract, Event Name, and Block

**GET** `/events/contract/{contractAddress}/{eventName}/{blockNumber}`

Filters events by an **exact** block number match on `{blockNumber}`. The `block` query parameter (minimum block) still applies.

**Example:** `https://mainnet.tron.tronql.com/events/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet/4835773`

***

### Filter Events by Contract and Event Name (Exact Block)

**GET** `/events/filter/contract/{contractAddress}/{eventName}`

Like the endpoint above, but the `block` query parameter filters by an **exact** block number instead of a minimum.

**Query Parameters:**

| Name    | Type   | Description                     | Default    |
| ------- | ------ | ------------------------------- | ---------- |
| `limit` | int    | Page size (max 100)             | 25         |
| `sort`  | string | Sort field                      | -timeStamp |
| `start` | int    | Page number (1-based)           | 1          |
| `since` | int    | Minimum timestamp (ms)          | 0          |
| `block` | int    | **Exact** block number to match | —          |

**Example:** `https://mainnet.tron.tronql.com/events/filter/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet?block=4835773`

***

## Blocks

### List Blocks

**GET** `/blocks`

**Query Parameters:**

| Name       | Type   | Description           | Default    |
| ---------- | ------ | --------------------- | ---------- |
| `limit`    | int    | Page size (max 100)   | 25         |
| `sort`     | string | Sort field            | -timeStamp |
| `start`    | int    | Page number (1-based) | 1          |
| `block`    | int    | Minimum block number  | 0          |
| `block_to` | int    | Maximum block number  | —          |

**Response:**

```json
{
  "total": 65432100,
  "data": [
    {
      "blockNumber": 4835773,
      "blockHash": "000000000049c11f...",
      "transactionSize": 42,
      "transactionList": ["9a4f09...", "cd402e..."],
      "timeStamp": 1620000000000,
      "triggerName": "block",
      "latestSolidifiedBlockNumber": 4835755
    }
  ]
}
```

**Example:** `https://mainnet.tron.tronql.com/blocks?limit=25&sort=-timeStamp`

***

### Get Block by Hash or Number

**GET** `/blocks/{hashOrNumber}`

Accepts either a block hash (hex string) or a block number (integer). When the value parses as an integer it is looked up by block number; otherwise it is looked up by hash.

**Response:** `{ "block": { ...BlockItem } }`

**Examples:** `https://mainnet.tron.tronql.com/blocks/000000000049c11f15d4e91e988bc950fa9f194d2cb2e04cda76675dbb349009` `https://mainnet.tron.tronql.com/blocks/4835773`

***

### Get Latest Solidified Block Number

**GET** `/blocks/latestSolidifiedBlockNumber`

Returns the current solidified block number as plain text.

**Example:** `https://mainnet.tron.tronql.com/blocks/latestSolidifiedBlockNumber` → `4835755`

***

### Get Blocks Total

**GET** `/blocks/total`

Returns total block count as plain text.

**Example:** `https://mainnet.tron.tronql.com/blocks/total` → `65432100`

***

## Contract Logs

Raw EVM-style logs (topics + data), without ABI decoding. For decoded results use [Contract Events (ABI-decoded)](#contract-events-abi-decoded).

> **Note:** These endpoints use **0-based** page numbers (`start=0`).

### Contract Log Object

```json
{
  "topicList": ["0xddf252ad..."],
  "data": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "transactionId": "f7440e...",
  "contractAddress": "TXDk8m...",
  "callerAddress": "TJ7yJN...",
  "originAddress": "TJ7yJN...",
  "creatorAddress": "TXDk8m...",
  "blockNumber": 4835773,
  "timeStamp": 1620000000000,
  "triggerName": "triggerSmartContract",
  "uniqueId": "f7440e..._0",
  "removed": false,
  "latestSolidifiedBlockNumber": 4835755,
  "abiString": null,
  "rawData": {
    "address": "TXDk8m...",
    "topics": [{ "data": "0xddf252ad..." }],
    "data": "0x..."
  }
}
```

***

### List Contract Logs

**GET** `/contractlogs`

**Query Parameters:**

| Name    | Type   | Description               | Default    |
| ------- | ------ | ------------------------- | ---------- |
| `limit` | int    | Page size (max 200)       | 25         |
| `sort`  | string | Sort field                | -timeStamp |
| `start` | int    | Page number (**0-based**) | 0          |
| `block` | int    | Filter by block number    | —          |

**Response:** `{ "total": 42, "data": [ ...ContractLog ] }`

> **Note:** `total` reflects the number of records returned on this page, not the database-wide count. Use `/contractlogs/total` for the true count.

**Example:** `https://mainnet.tron.tronql.com/contractlogs?limit=25&sort=-timeStamp`

***

### Get Contract Logs Total

**GET** `/contractlogs/total`

Returns total contract log count as plain text.

**Example:** `https://mainnet.tron.tronql.com/contractlogs/total` → `12345678`

***

### Get Contract Logs by Transaction

**GET** `/contractlogs/transaction/{transactionId}`

Returns all contract logs for a transaction as a plain JSON array (no `{ total, data }` wrapper).

**Example:** `https://mainnet.tron.tronql.com/contractlogs/transaction/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55`

***

### Get Contract Logs by Contract Address

**GET** `/contractlogs/contract/{contractAddress}`

**Query Parameters:**

| Name        | Type   | Description                         | Default    |
| ----------- | ------ | ----------------------------------- | ---------- |
| `limit`     | int    | Page size (max 200)                 | 25         |
| `sort`      | string | Sort field                          | -timeStamp |
| `start`     | int    | Page number (**0-based**)           | 0          |
| `since`     | int    | Minimum timestamp (ms)              | 0          |
| `block`     | int    | Minimum block number (`-1` to skip) | —          |
| `eventName` | string | Filter by event name                | —          |

**Response:** Plain JSON array of ContractLog objects (no `{ total, data }` wrapper).

**Example:** `https://mainnet.tron.tronql.com/contractlogs/contract/TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz?eventName=Transfer&limit=25`

***

### Get Contract Log by Unique ID

**GET** `/contractlogs/uniqueId/{uniqueId}`

Returns a single contract log. Returns 404 if not found.

**Example:** `https://mainnet.tron.tronql.com/contractlogs/uniqueId/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55_0`

***

## Contract Events (ABI-decoded)

These endpoints accept a JSON request body with ABI field filters and return decoded event data. They use the same response format as [TronGrid-Compatible Events](#trongrid-compatible-events) but wrapped in `{ "total", "data" }`.

> **Note:** These endpoints use **0-based** page numbers (`start=0`).

### Decoded Event Object

```json
{
  "transaction_id": "9a4f09...",
  "block_timestamp": 1620000000000,
  "block_number": 4835773,
  "result_type": { "_from": "address", "_to": "address", "value": "uint256" },
  "result": { "_from": "TJ7yJN...", "_to": "TAEcoD...", "value": "1000000" },
  "event_index": 0,
  "event_name": "Transfer",
  "contract_address": "TR7NHq...",
  "caller_contract_address": "TJ7yJN...",
  "_unconfirmed": true
}
```

> `_unconfirmed` is only present when the event is in an unconfirmed block.

***

### Get Decoded Events by Contract Address

**POST** `/contract/contractAddress/{contractAddress}`

**Query Parameters:**

| Name        | Type   | Description                         | Default    |
| ----------- | ------ | ----------------------------------- | ---------- |
| `limit`     | int    | Page size (max 200)                 | 25         |
| `sort`      | string | Sort field                          | -timeStamp |
| `start`     | int    | Page number (**0-based**)           | 0          |
| `since`     | int    | Minimum timestamp (ms)              | 0          |
| `block`     | int    | Minimum block number (`-1` to skip) | —          |
| `eventName` | string | Filter by event name                | —          |

**Request Body:** JSON object with decoded field name → value pairs to filter results.

```json
{ "_to": "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8" }
```

**Response:** `{ "total": 42, "data": [ ...DecodedEvent ] }`

**Example:**

```
POST https://mainnet.tron.tronql.com/contract/contractAddress/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t?eventName=Transfer
Content-Type: application/json

{ "_to": "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8" }
```

***

### Get Decoded Events by Transaction

**POST** `/contract/transaction/{transactionId}`

**Request Body:** JSON object with decoded field name → value pairs to filter results.

**Response:** `{ "total": 42, "data": [ ...DecodedEvent ] }`

**Example:**

```
POST https://mainnet.tron.tronql.com/contract/transaction/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55
Content-Type: application/json

{}
```

***

### Get Decoded Event by Unique ID

**POST** `/contract/uniqueId/{uniqueId}`

**Request Body:** JSON object with decoded field name → value pairs to filter results.

**Response:** `{ "total": 1, "data": [ ...DecodedEvent ] }`

**Example:**

```
POST https://mainnet.tron.tronql.com/contract/uniqueId/f7440eb396632db8e279078069a55abc0a3c018072b458bbd4eeddafc4782b55_0
Content-Type: application/json

{}
```

***

## TronGrid-Compatible Events

Drop-in replacement for the TronGrid event API. Use these endpoints to migrate from TronGrid without changing client code.

Response items use snake\_case field names and include `_unconfirmed` / `_fingerprint` markers.

### TronGrid Event Object

```json
{
  "transaction_id": "9a4f09...",
  "block_timestamp": 1620000000000,
  "block_number": 4835773,
  "result_type": { "_from": "address", "_to": "address", "value": "uint256" },
  "result": { "_from": "TJ7yJN...", "_to": "TAEcoD...", "value": "1000000" },
  "event_index": 0,
  "event_name": "Transfer",
  "contract_address": "TR7NHq...",
  "caller_contract_address": "TJ7yJN...",
  "_unconfirmed": true,
  "_fingerprint": "00000001"
}
```

> `_unconfirmed` is only present on unconfirmed events.\
> `_fingerprint` is only present on the **last item** of a page; pass it as the `fingerprint` query parameter to retrieve the next page.

***

### Common TronGrid Query Parameters

| Name              | Type   | Description                                               | Default    |
| ----------------- | ------ | --------------------------------------------------------- | ---------- |
| `size`            | int    | Page size (max 200)                                       | 20         |
| `sort`            | string | Sort field; also accepts `block_timestamp`                | -timeStamp |
| `start`           | int    | Page number (0-based)                                     | 0          |
| `since`           | int    | Minimum timestamp (ms)                                    | 0          |
| `fromTimestamp`   | int    | Alias for `since`                                         | —          |
| `fingerprint`     | string | Pagination cursor from previous response's `_fingerprint` | —          |
| `onlyConfirmed`   | bool   | `true` to return only solidified events                   | —          |
| `onlyUnconfirmed` | bool   | `true` to return only unconfirmed events                  | —          |

> `onlyConfirmed` and `onlyUnconfirmed` are mutually exclusive.

***

### Get Events by Transaction (TronGrid)

**GET** `/event/transaction/{transactionId}`

**Example:** `https://mainnet.tron.tronql.com/event/transaction/cd402e64cad7e69c086649401f6427f5852239f41f51a100abfc7beaa8aa0f9c`

***

### Get Latest Solidified Block Number (TronGrid)

**GET** `/event/contract/latestSolidifiedBlockNum`

Returns the latest solidified block number as plain text.

**Example:** `https://mainnet.tron.tronql.com/event/contract/latestSolidifiedBlockNum` → `4835755`

***

### Get Events by Contract Address (TronGrid)

**GET** `/event/contract/{contractAddress}`

**Example:** `https://mainnet.tron.tronql.com/event/contract/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t?size=20&onlyConfirmed=true`

***

### Get Events by Contract Address and Event Name (TronGrid)

**GET** `/event/contract/{contractAddress}/{eventName}`

**Example:** `https://mainnet.tron.tronql.com/event/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet?size=20`

***

### Get Events by Contract, Event Name, and Block (TronGrid)

**GET** `/event/contract/{contractAddress}/{eventName}/{blockNumber}`

`{blockNumber}` accepts a numeric block number or the special value `latest`, which resolves to the current solidified block.

**Example:** `https://mainnet.tron.tronql.com/event/contract/TMYcx6eoRXnePKT1jVn25ZNeMNJ6828HWk/Bet/latest`

***

## TRC20

### Get TRC20 Token Holders

**GET** `/trc20/getholder/{contractAddress}`

Returns a deduplicated list of addresses that have appeared as sender or recipient in Transfer events for the given contract.

**Response:**

```json
["TJ7yJNWS8RmvpXcAyXBhvFDfGpV9ZYc3vt", "TAEcoD8J7P5QjWT32r31gat8L7Sga2qUy8"]
```

**Example:** `https://mainnet.tron.tronql.com/trc20/getholder/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tronql.com/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.