> For the complete documentation index, see [llms.txt](https://docs.mercurydata.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mercurydata.app/retroshades/get-started/querying-retroshades.md).

# Querying Retroshades

For each retroshade struct defined in the contract, a table on the database will be created that can be queried using `POST /retroshade/query`:

```bash
curl -X POST https://mainnet.mercurydata.app/rest/retroshade/query \
-H "Authorization: Bearer <yourjwt>" \
-H 'Content-Type: application/json' \
-d '{
  "query": "SELECT * FROM retroshade.program_1_liquidity_event LIMIT 50"
}'
```

### Table naming

Tables are named `retroshade.program_{id}_{target}` where:

* `id` is the integer ID assigned to your program at deploy time (returned by `POST /retroshade/deploy` and visible in `GET /retroshade/list`)
* `target` is the snake\_case version of the struct name used in your retroshade emit (e.g. `LiquidityEvent` becomes `liquidity_event`)

To discover the exact table names for your programs, use `GET /retroshade/tables`:

```bash
curl https://mainnet.mercurydata.app/rest/retroshade/tables \
-H "Authorization: Bearer <yourjwt>"
```

Response:

```json
[
  {
    "table_name": "program_1_liquidity_event",
    "project_name_plain": "my-retroshade-program"
  }
]
```

### Mercury-injected columns

Every retroshade table has three columns added automatically by Mercury. Do not define these in your struct:

| Column              | Type        | Description                                              |
| ------------------- | ----------- | -------------------------------------------------------- |
| `contract_id`       | TEXT        | Soroban contract that triggered the emit                 |
| `transaction`       | TEXT        | Transaction hash                                         |
| `_mercury_event_id` | TEXT UNIQUE | Mercury dedup key -- do not use as a semantic identifier |

### List Retroshades Subscriptions

Returns all retroshade programs deployed by the authenticated user.

**Endpoint**: `GET /retroshade/list`

```bash
curl https://mainnet.mercurydata.app/rest/retroshade/list \
-H "Authorization: Bearer <yourjwt>"
```

Response:

```json
[
  {
    "id": 1,
    "project_name": "my-retroshade-program",
    "contracts": [
      "CDVNV4..."
    ],
    "running": true
  }
]
```