# Searches (`mttr_queries`)

Updated October 24, 2026.

## What does mttr_queries do?

The searches a site’s pages were shown for, from Search Console, with clicks, impressions and average place: by query, by page, or only those close to the top. A key may make this call on the sites it has claimed.

Who may call it: Your claimed sites.

## When to use it

- You want to know what people search to find a site.
- You want searches sitting just off the first page.

## What you ask

You might say: “Which searches is example.com close to the top for?”

```
mttr_queries({ site: "example.com" })
```

| Argument | Type | Needed | What it is |
| --- | --- | --- | --- |
| `site` | Text | Yes | The site, as a domain such as example.com. |
| `show` | One of these: queries, pages, near, unanswered, better | No | queries (the default), pages, near: queries close to the top, unanswered: searches no passage on the site comes close to, brand searches left out, or better: searches another page reads closer to than the one Google shows. The last two are most seen first. |
| `page` | Text | No | A full page address, to list only the queries that page was shown for. |
| `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 search with clicks, impressions and average place.
- With show set to unanswered, the searches no page on the site answers; with better, those where another of its pages reads closer than the one Google shows.
- Searches read from Search Console are marked as quoted. A site whose Search Console has not been read gets nothing, and the answer says so.

A sample, with made-up sites and figures:

| Search | Clicks | Shown | Place |
| --- | --- | --- | --- |
| drain cleaning near me | 38 | 1,204 | 6.2 |
| septic pumping cost | 12 | 880 | 9.8 |
| clogged sink fix | 4 | 610 | 14.1 |

## Over HTTP

```
curl "https://mttr.si/api/v1/sites/example.com/queries" \
  -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. |
| The key has not claimed the site | 404 | Claim it with `mttr_claim`, then `mttr_claim_check`. |

## 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_queries in the API reference](https://mttr.si/docs/reference#mttr_queries).

## Goes with

- [Search traffic](https://mttr.si/docs/tools/traffic.md)
- [Citations so far](https://mttr.si/docs/tools/citations.md)