Rate Limits

The Matter API enforces per-user rate limits to ensure fair usage and protect the service.

Limits

Operation	Limit	Applies to
Read	120 requests/min	All `GET` requests
Write	30 requests/min	`POST`, `PATCH`, `DELETE` requests
Save	10 requests/min	`POST /v1/items` (saving new URLs)
Search	30 requests/min	`GET /v1/search`
Markdown	20 requests/min	`GET` requests with `?include=markdown`
Burst	5 requests/sec	All requests (short-term ceiling)

Save requests have a lower limit because each save triggers background content extraction (fetching, parsing, and processing the URL). Markdown requests count against both the read and markdown limits because these responses are significantly larger and more expensive to serve. Limits are applied per API token (i.e., per user account).

Rate limit headers

Every response includes headers showing your current quota:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1711814400

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets.

Handling 429 responses

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711814400

Recommended retry strategy

import time
import requests

def api_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get("Retry-After", 10))
        time.sleep(retry_after)

    raise Exception("Rate limit exceeded after retries")

Do not retry immediately or in a tight loop. Always respect the Retry-After value. Clients that ignore rate limits may have their tokens temporarily suspended.

Best practices

Use incremental sync instead of full fetches

The updated_since parameter on list endpoints dramatically reduces the number of requests needed to stay in sync. Fetch everything once, then sync only changes.

Use larger page sizes

Set limit=100 (the maximum) to reduce the number of requests needed to paginate through results.

Cache responses locally

Store items locally and only refetch when needed. The updated_at field tells you if an item has changed.

Batch your writes

If you’re tagging many items, space your requests rather than firing them all at once.

Getting Started

Concepts

API Reference

Limits

Rate limit headers

Handling 429 responses

Recommended retry strategy

Best practices

​Limits

​Rate limit headers

​Handling 429 responses

​Recommended retry strategy

​Best practices

Limits

Rate limit headers

Handling 429 responses

Recommended retry strategy

Best practices