# GET /referrals/leaderboard

**Resource:** [Referrals](./referrals.md)  
**Scopes:** `referrals:read`  
**Write operation:** no

Top referrers ranked by converted_referrals desc, then total_referrals desc. Returns up to limit entries with contact details, total_referrals, converted_referrals, and conversion_rate.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `limit` | query | number | no | Max entries (default 10, max 50). |
| `only_converted` | query | boolean | no | When true, only count referrals with status="converted". |

## Request example

```bash
curl "https://ucqwijexmjctglmrxlej.supabase.co/functions/v1/api/v1/referrals/leaderboard?limit=10" \
  -H "Authorization: Bearer tp_live_..."
```

## Response example

```json
{
  "data": {
    "leaderboard": [
      {
        "contact": {
          "id": "1068084c-f975-4bb8-be1b-4f0a2f0843be",
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@example.com",
          "images": []
        },
        "total_referrals": 5,
        "converted_referrals": 3,
        "conversion_rate": 0.6
      }
    ]
  },
  "meta": { "credits_remaining": 4500 }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`