# Leaderboard (`mttr_leaderboard`)

Updated October 24, 2026.

## What does mttr_leaderboard do?

Every ranked site by the score of its latest read, or the board of one crowd: a line of work, a state, a city or a size. Or one of the records, such as the most improved. Any key may make this call, on any public site.

Who may call it: Any key.

## When to use it

- You want to know where a site ranks.
- You want the best sites in a line of work to learn from.

## What you ask

You might say: “Show me the leaderboard for the trades.”

```
mttr_leaderboard({})
```

| Argument | Type | Needed | What it is |
| --- | --- | --- | --- |
| `in` | Text | No | A line of work, such as trades, for its own board. Left out, every site. |
| `state` | Text | No | A US state by its two letters, such as MO, for the board of the sites there. |
| `city` | Text | No | A city in that state, such as Dallas, for the board of the sites there. Needs state. |
| `size` | One of these: 1-10, 11-50, 51-99, 100-plus | No | Sites of about one size, by the pages a read took of them. |
| `record` | One of these: fastest, improved, stages, answer-first, biggest | No | One record in place of the places. |
| `limit` | Number | No | How many to return. |
| `offset` | Number | No | How many to skip, for the next part of a long list. |

## What comes back

- Each site with its place, score, stages and pages read.
- Sites kept unnamed go by a code.

A sample, with made-up sites and figures:

| Place | Site | Score | Before |
| --- | --- | --- | --- |
| 1 | north.example | 91 | 88 |
| 2 | rival.example | 89 | 89 |
| 3 | Unnamed site | 87 | 80 |

A score says pages are well formed. It does not say an assistant cites the site.

## Over HTTP

```
curl "https://mttr.si/api/v1/leaderboard" \
  -H "Authorization: Bearer $MTTR_KEY"
```

## When it fails

| When | Status | What to do |
| --- | --- | --- |
| Your assistant has no key yet | 401 over MCP | Sign up with `mttr_signup`, then connect again with the key it gives. |

## Sources

- [Model Context Protocol: tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools), Model Context Protocol: How an assistant calls a tool.

The call in full: [mttr_leaderboard in the API reference](https://mttr.si/docs/reference#mttr_leaderboard).

## Goes with

- [Name a site on the leaderboard](https://mttr.si/docs/tools/list.md)
- [A site against its market](https://mttr.si/docs/tools/market.md)