# The crawl (`mttr_crawls`)

Updated October 24, 2026.

## What does mttr_crawls do?

The crawl as it stands: the sites being read now, the next in line, and how the reads that ended over the last 1, 7 or 30 days ended. Only whoever runs this mttr may make this call.

Who may call it: Owner.

## When to use it

- You run mttr and want to see how the crawl is going.

## What you ask

You might say: “How is the crawl going?”

```
mttr_crawls({})
```

| Argument | Type | Needed | What it is |
| --- | --- | --- | --- |
| `days` | Number | No | The range, in days: 1, 7 or 30. The week when left out or anything else. |

## What comes back

- Sites being read now and next in line.
- How recent reads ended, by count.

A sample, with made-up sites and figures:

| Ended as | Last day | Last 7 days |
| --- | --- | --- |
| Read | 412 | 2,904 |
| Closed to crawlers | 31 | 198 |
| Failed | 6 | 44 |

## Over HTTP

```
curl "https://mttr.si/api/v1/crawls" \
  -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 is a person’s, not the owner’s | 403 | Nothing: only whoever runs mttr makes this call. |

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

## Goes with

- [What happened lately](https://mttr.si/docs/tools/events.md)
- [Where a read stands](https://mttr.si/docs/tools/job.md)