Search

GET

curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
  -H "Authorization: Bearer mat_your_token_here"

response = requests.get(
    "https://api.getmatter.com/public/v1/search",
    headers={"Authorization": f"Bearer {token}"},
    params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
    print(item["title"])

const response = await fetch(
  "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
  { headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));

{
  "object": "search_results",
  "items": {
    "object": "list",
    "results": [
      {
        "object": "item",
        "id": "itm_r9f3a",
        "title": "Introduction to Machine Learning",
        "url": "https://example.com/intro-ml",
        "site_name": "example.com",
        "author": {
          "object": "author",
          "id": "aut_p4w7q",
          "name": "Jane Smith"
        },
        "status": "queue",
        "is_favorite": false,
        "content_type": "article",
        "processing_status": "completed",
        "word_count": 4200,
        "reading_progress": 0.35,
        "image_url": null,
        "library_position": 58974321000,
        "inbox_position": null,
        "tags": [],
        "updated_at": "2026-03-30T19:15:00Z"
      },
      {
        "object": "item",
        "id": "itm_k4m2n",
        "title": "Neural Networks from Scratch",
        "url": "https://example.com/nn-scratch",
        "site_name": "example.com",
        "author": null,
        "status": null,
        "is_favorite": false,
        "content_type": "article",
        "processing_status": "completed",
        "word_count": 8100,
        "reading_progress": 0.0,
        "image_url": null,
        "library_position": null,
        "inbox_position": null,
        "tags": [],
        "updated_at": "2026-03-28T12:00:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}

Search across Matter. Results are grouped by type, each with independent pagination. Currently supports items; more types will be added in future releases.

Query Parameters

string

required

Search query string (min 2 characters). Supports operators:

"exact phrase" — required phrase match
-excluded — exclude articles containing a term
by:author — filter by author or publisher name
site:domain — filter by domain or publisher
title:word — match in title only

Examples: machine learning, "deep work", by:graham site:paulgraham.com

string

required

Comma-separated list of result types to include. Currently supported: items.

string

Filter for item results. Restricts results to items with the given status. Comma-separated for multiple values. Omit to search all content. Only applies when items is in the type parameter.

queue — queue items only
archive — archived items only
queue,archive — both queue and archive

integer

default:25

Maximum results per type. Min 1, max 100.

string

Cursor for the next page of results. Obtained from next_cursor in a previous response.

Response

string

required

Always "search_results".

object

Matching items, ranked by relevance. Present when items is in the type parameter.

Show items properties

string

Always "list".

Item[]

Array of item objects ranked by relevance.

Show Item properties

string

Always "item".

string

Prefixed item ID (e.g. itm_r9f3a).

string

The item’s title.

string

Original URL of the content.

string

The source website name.

object | null

The item’s author, if known.

Show Author properties

string

Always "author".

string

Prefixed author ID (e.g. aut_p4w7q).

string

Author name.

string | null

Status: inbox, queue, or archive. null when the item has no status.

string

Type of content: article, podcast, pdf, or tweet.

string

Content extraction status: processing or completed.

boolean

Whether the item is favorited.

number

Reading progress from 0.0 to 1.0.

integer | null

Estimated word count.

string | null

URL of the item’s hero image.

string | null

Short excerpt or description.

integer | null

Position in the library. null if not in the library.

integer | null

Position in the inbox feed. null if not in the inbox.

Tag[]

Tags applied to this item.

string

ISO 8601 timestamp of the last change.

boolean

Whether there are more results after this page.

string | null

Cursor for the next page, or null.

curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
  -H "Authorization: Bearer mat_your_token_here"

response = requests.get(
    "https://api.getmatter.com/public/v1/search",
    headers={"Authorization": f"Bearer {token}"},
    params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
    print(item["title"])

const response = await fetch(
  "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
  { headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));

{
  "object": "search_results",
  "items": {
    "object": "list",
    "results": [
      {
        "object": "item",
        "id": "itm_r9f3a",
        "title": "Introduction to Machine Learning",
        "url": "https://example.com/intro-ml",
        "site_name": "example.com",
        "author": {
          "object": "author",
          "id": "aut_p4w7q",
          "name": "Jane Smith"
        },
        "status": "queue",
        "is_favorite": false,
        "content_type": "article",
        "processing_status": "completed",
        "word_count": 4200,
        "reading_progress": 0.35,
        "image_url": null,
        "library_position": 58974321000,
        "inbox_position": null,
        "tags": [],
        "updated_at": "2026-03-30T19:15:00Z"
      },
      {
        "object": "item",
        "id": "itm_k4m2n",
        "title": "Neural Networks from Scratch",
        "url": "https://example.com/nn-scratch",
        "site_name": "example.com",
        "author": null,
        "status": null,
        "is_favorite": false,
        "content_type": "article",
        "processing_status": "completed",
        "word_count": 8100,
        "reading_progress": 0.0,
        "image_url": null,
        "library_position": null,
        "inbox_position": null,
        "tags": [],
        "updated_at": "2026-03-28T12:00:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}

curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
  -H "Authorization: Bearer mat_your_token_here"

response = requests.get(
    "https://api.getmatter.com/public/v1/search",
    headers={"Authorization": f"Bearer {token}"},
    params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
    print(item["title"])

const response = await fetch(
  "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
  { headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));

{
  "object": "search_results",
  "items": {
    "object": "list",
    "results": [
      {
        "object": "item",
        "id": "itm_r9f3a",
        "title": "Introduction to Machine Learning",
        "url": "https://example.com/intro-ml",
        "site_name": "example.com",
        "author": {
          "object": "author",
          "id": "aut_p4w7q",
          "name": "Jane Smith"
        },
        "status": "queue",
        "is_favorite": false,
        "content_type": "article",
        "processing_status": "completed",
        "word_count": 4200,
        "reading_progress": 0.35,
        "image_url": null,
        "library_position": 58974321000,
        "inbox_position": null,
        "tags": [],
        "updated_at": "2026-03-30T19:15:00Z"
      },
      {
        "object": "item",
        "id": "itm_k4m2n",
        "title": "Neural Networks from Scratch",
        "url": "https://example.com/nn-scratch",
        "site_name": "example.com",
        "author": null,
        "status": null,
        "is_favorite": false,
        "content_type": "article",
        "processing_status": "completed",
        "word_count": 8100,
        "reading_progress": 0.0,
        "image_url": null,
        "library_position": null,
        "inbox_position": null,
        "tags": [],
        "updated_at": "2026-03-28T12:00:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
}

Getting Started

Concepts

API Reference

Query Parameters

Response

​Query Parameters

​Response

Query Parameters

Response