> 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/monitoring-execution.md).

# Monitoring Execution

After deploying a Retroshades program you can inspect its runtime status, per-transaction execution history and aggregate statistics through three endpoints.

### Program status

Returns aggregate statistics for a deployed program. Counts are computed over the 500 most recent execution records retained per program.

**Endpoint:** `GET /retroshade/{id}/status`\
**Auth:** JWT required

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

Response:

```json
{
  "program_id": 1,
  "project_name": "my-retroshade-program",
  "running": true,
  "last_success_ledger": 62549580,
  "last_error_ledger": null,
  "last_error_message": null,
  "total_executions": 500,
  "total_errors": 0,
  "avg_execution_ms": 3
}
```

### Execution log

Returns a paginated list of per-transaction execution records, newest first. Up to 500 records are retained per program.

**Endpoint:** `GET /retroshade/{id}/executions`\
**Auth:** JWT required\
**Query params:**

| Param         | Default | Max | Description                                           |
| ------------- | ------- | --- | ----------------------------------------------------- |
| `limit`       | 50      | 200 | Number of records to return                           |
| `from_ledger` | --      | --  | Return only records at or before this ledger sequence |

```bash
curl "https://mainnet.mercurydata.app/rest/retroshade/1/executions?limit=10" \
  -H "Authorization: Bearer <yourjwt>"
```

Response:

```json
[
  {
    "ledger_sequence": 62549580,
    "tx_hash": "3e1f7e1ceca397a70d0bb1a2bef884731809b839b865be8fb77bf55ac08abc05",
    "status": "success",
    "error_message": null,
    "rows_written": 2,
    "execution_ms": 4,
    "created_at": "2026-05-13T12:05:36Z"
  }
]
```

`status` is either `"success"` or `"error"`. On error, `error_message` contains the failure detail and `rows_written` will be 0.

### Per-ledger stats

Returns per-ledger aggregate stats for a program, ordered newest first. Useful for tracking throughput and spotting error spikes across ledgers. Records older than 30 days are pruned automatically.

**Endpoint:** `GET /retroshade/{id}/stats`\
**Auth:** JWT required\
**Query params:**

| Param    | Description                                      |
| -------- | ------------------------------------------------ |
| `source` | Filter by `live` or `backfill` (default: all)    |
| `from`   | Return records at or after this ledger sequence  |
| `to`     | Return records at or before this ledger sequence |
| `limit`  | Number of records to return                      |

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

Response:

```json
[
  {
    "ledger_sequence": 62549580,
    "source": "live",
    "executions": 3,
    "error_count": 0,
    "rows_written": 6,
    "total_execution_ms": 12,
    "created_at": "2026-06-12T19:26:22Z"
  }
]
```

`source` is `"live"` for normal ingestion and `"backfill"` for backfill runs.

Make sure to change the endpoint if you're on testnet.