> ## 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.

# List Items

> Returns a paginated list of items in your library.

## Query Parameters

<ParamField query="status" type="string" default="all">
  Filter by item status. Comma-separated for multiple: `queue,archive`. Values: `inbox`, `queue`, `archive`, or `all`.
</ParamField>

<ParamField query="order" type="string" default="updated">
  Sort order for results. Values:

  * `updated` — Sort by last-updated timestamp (default). Best for [incremental sync](/api/pagination#incremental-sync).
  * `library_position` — Sort by the item's library position (manual queue ordering). Items without a library entry sort last.
  * `inbox_position` — Sort by the item's inbox feed position (newest first). Items not in the inbox sort last.

  No status filter is required for position orderings. All items include `library_position` and `inbox_position` fields regardless of the order used, enabling clients to sort locally after incremental sync.
</ParamField>

<ParamField query="is_favorite" type="boolean">
  Filter to favorited items only.
</ParamField>

<ParamField query="tag" type="string">
  Filter to items with a specific tag ID. Comma-separated for multiple: `tag_n5j2x,tag_k3m9p` (returns items matching **any** of the tags).
</ParamField>

<ParamField query="content_type" type="string">
  Filter by content type. Comma-separated for multiple: `article,podcast`. Values: `article`, `video`, `podcast`, `pdf`, `tweet`, `newsletter`.
</ParamField>

<ParamField query="updated_since" type="string">
  ISO 8601 timestamp. Return only items updated after this time. Useful for [incremental sync](/api/pagination#incremental-sync).

  An item's `updated_at` reflects **any** change to the item or its associated data — status changes, reading progress, favorites, tag additions/removals, new annotations, and content re-extraction all advance the timestamp. For inbox items that have never been interacted with, `updated_at` is the time the item appeared in your inbox.
</ParamField>

<ParamField query="limit" type="integer" default={25}>
  Number of items per page. 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 `"list"`.
</ResponseField>

<ResponseField name="results" type="array" required>
  Array of item objects. See [Get Item](/api/items/get) for the full item schema.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether there are more results after this page.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor to fetch the next page. `null` when there are no more results.
</ResponseField>

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

  ```python Python theme={null}
  response = requests.get(
      "https://api.getmatter.com/public/v1/items",
      headers={"Authorization": f"Bearer {token}"},
      params={"status": "queue", "limit": 10}
  )
  items = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.getmatter.com/public/v1/items?status=queue&limit=10",
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const items = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "results": [
      {
        "object": "item",
        "id": "itm_r9f3a",
        "title": "How to Do Great Work",
        "url": "https://paulgraham.com/greatwork.html",
        "site_name": "paulgraham.com",
        "author": {
          "object": "author",
          "id": "aut_p4w7q",
          "name": "Paul Graham"
        },
        "status": "queue",
        "is_favorite": false,
        "content_type": "article",
        "word_count": 11842,
        "reading_progress": 0.35,
        "image_url": "https://cdn.getmatter.com/images/itm_r9f3a.jpg",
        "library_position": 58974321000,
        "inbox_position": null,
        "tags": [
          {
            "object": "tag",
            "id": "tag_n5j2x",
            "name": "essays"
          }
        ],
        "updated_at": "2026-03-30T19:15:00Z"
      }
    ],
    "has_more": true,
    "next_cursor": "eyJpZCI6MTIzNH0="
  }
  ```
</ResponseExample>