> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmatter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Full-text search across Matter, grouped by type.

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

<ParamField query="query" type="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`
</ParamField>

<ParamField query="type" type="string" required>
  Comma-separated list of result types to include. Currently supported: `items`.
</ParamField>

<ParamField query="status" type="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
</ParamField>

<ParamField query="limit" type="integer" default={25}>
  Maximum results per type. Min 1, max 100.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for the next page of results. Obtained from `next_cursor` in a previous response.
</ParamField>

## Response

<ResponseField name="object" type="string" required>
  Always `"search_results"`.
</ResponseField>

<ResponseField name="items" type="object">
  Matching items, ranked by relevance. Present when `items` is in the `type` parameter.

  <Expandable title="items properties">
    <ResponseField name="object" type="string">Always `"list"`.</ResponseField>

    <ResponseField name="results" type="Item[]">
      Array of item objects ranked by relevance.

      <Expandable title="Item properties">
        <ResponseField name="object" type="string">Always `"item"`.</ResponseField>
        <ResponseField name="id" type="string">Prefixed item ID (e.g. `itm_r9f3a`).</ResponseField>
        <ResponseField name="title" type="string">The item's title.</ResponseField>
        <ResponseField name="url" type="string">Original URL of the content.</ResponseField>
        <ResponseField name="site_name" type="string">The source website name.</ResponseField>

        <ResponseField name="author" type="object | null">
          The item's author, if known.

          <Expandable title="Author properties">
            <ResponseField name="object" type="string">Always `"author"`.</ResponseField>
            <ResponseField name="id" type="string">Prefixed author ID (e.g. `aut_p4w7q`).</ResponseField>
            <ResponseField name="name" type="string">Author name.</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="status" type="string | null">
          Status: `inbox`, `queue`, or `archive`. `null` when the item has no status.
        </ResponseField>

        <ResponseField name="content_type" type="string">Type of content: `article`, `podcast`, `pdf`, or `tweet`.</ResponseField>
        <ResponseField name="processing_status" type="string">Content extraction status: `processing` or `completed`.</ResponseField>
        <ResponseField name="is_favorite" type="boolean">Whether the item is favorited.</ResponseField>
        <ResponseField name="reading_progress" type="number">Reading progress from `0.0` to `1.0`.</ResponseField>
        <ResponseField name="word_count" type="integer | null">Estimated word count.</ResponseField>
        <ResponseField name="image_url" type="string | null">URL of the item's hero image.</ResponseField>
        <ResponseField name="excerpt" type="string | null">Short excerpt or description.</ResponseField>
        <ResponseField name="library_position" type="integer | null">Position in the library. `null` if not in the library.</ResponseField>
        <ResponseField name="inbox_position" type="integer | null">Position in the inbox feed. `null` if not in the inbox.</ResponseField>
        <ResponseField name="tags" type="Tag[]">Tags applied to this item.</ResponseField>
        <ResponseField name="updated_at" type="string">ISO 8601 timestamp of the last change.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="has_more" type="boolean">Whether there are more results after this page.</ResponseField>
    <ResponseField name="next_cursor" type="string | null">Cursor for the next page, or `null`.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
    -H "Authorization: Bearer mat_your_token_here"
  ```

  ```python Python theme={null}
  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"])
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>