> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fluxerlist.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fluxerlist.com/_mcp/server.

# Reward your voters

Votes are the most direct signal that someone likes your community. The voters endpoints return who voted and when, so you can hand out a role, a perk, or a shout-out.

You'll need an [API key](/api-quickstart) from the account that **owns** the listing. Co-admins and co-developers can't use the voters endpoints.

## The endpoints

| Listing | Endpoint                          | `{id}` is            |
| ------- | --------------------------------- | -------------------- |
| Server  | `GET /api/v1/servers/{id}/voters` | Your Fluxer guild ID |
| Bot     | `GET /api/v1/bots/{id}/voters`    | Your Fluxer bot ID   |

Both take the same query parameters and return the same shape.

| Parameter | Default | Description                                          |
| --------- | ------- | ---------------------------------------------------- |
| `page`    | 1       | Page number, starting at 1                           |
| `limit`   | 50      | Results per page. Values over 100 are capped at 100. |

```json
{
  "total": 42,
  "page": 1,
  "limit": 50,
  "voters": [
    {
      "username": "jack",
      "fluxerId": "123456789",
      "votedAt": "2026-09-18T12:00:00.000Z"
    }
  ]
}
```

Voters come back **newest first**. `username` is the person's display name if they've chosen to show it, otherwise their username. Use `fluxerId` to identify people, since names can change. It's a string, so don't parse it as a number.

## Fetch every voter

Walk the pages until you've collected `total` voters.

**`JavaScript`**

```javascript title="JavaScript"
async function fetchAllVoters(serverId) {
  const voters = [];
  let page = 1;
  let total = Infinity;

  while (voters.length < total) {
    const res = await fetch(
      `https://fluxerlist.com/api/v1/servers/${serverId}/voters?page=${page}&limit=100`,
      { headers: { Authorization: `Bearer ${process.env.FLUXERLIST_KEY}` } },
    );

    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? 30);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`FluxerList returned ${res.status}`);

    const body = await res.json();
    total = body.total;
    if (body.voters.length === 0) break;
    voters.push(...body.voters);
    page += 1;
  }

  return voters;
}
```

**`Python`**

```python title="Python"
import os
import time
import requests

def fetch_all_voters(server_id: str) -> list[dict]:
    voters, page, total = [], 1, None
    headers = {"Authorization": f"Bearer {os.environ['FLUXERLIST_KEY']}"}

    while total is None or len(voters) < total:
        res = requests.get(
            f"https://fluxerlist.com/api/v1/servers/{server_id}/voters",
            params={"page": page, "limit": 100},
            headers=headers,
            timeout=10,
        )
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", 30)))
            continue
        res.raise_for_status()

        body = res.json()
        total = body["total"]
        if not body["voters"]:
            break
        voters.extend(body["voters"])
        page += 1

    return voters
```

## Give voters something

Once you have the list, you can decide what a vote is worth. A few patterns that work:

* **Voter role.** Grant a role to anyone whose `votedAt` is within the last few days, and remove it after.
* **Leaderboard.** Count votes per `fluxerId` across time and post a monthly top list.
* **Milestones.** Announce when `total` crosses round numbers like 50 or 100.

> **Warning**
>
> Votes can be removed by the voter at any time, and the tokens they earned are reversed. Re-fetch the list before you hand out anything you can't take back.

> **Tip**
>
> Poll every few minutes at most, and cache the result. Fetching with `limit=100` keeps the number of requests down.

## Related

#### [Check a vote](/check-a-vote)

Look up a single user instead of paging through everyone.

#### [Bumps and votes](/bumps-and-votes)

How voting works for everyone else.

#### [API reference](/overview)

Every parameter and response.