List Items

GET

items

curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
  -H "Authorization: Bearer mat_your_token_here"

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

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

{
  "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="
}

Query Parameters

string

default:"all"

Filter by item status. Comma-separated for multiple: queue,archive. Values: inbox, queue, archive, or all.

string

default:"updated"

Sort order for results. Values:

updated — Sort by last-updated timestamp (default). Best for 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.

boolean

Filter to favorited items only.

string

Filter to items with a specific tag ID. Comma-separated for multiple: tag_n5j2x,tag_k3m9p (returns items matching any of the tags).

string

Filter by content type. Comma-separated for multiple: article,podcast. Values: article, video, podcast, pdf, tweet, newsletter.

string

ISO 8601 timestamp. Return only items updated after this time. Useful for 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.

integer

default:25

Number of items per page. Min 1, max 100.

string

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

Response

string

required

Always "list".

array

required

Array of item objects. See Get Item for the full item schema.

boolean

required

Whether there are more results after this page.

string

Cursor to fetch the next page. null when there are no more results.

curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
  -H "Authorization: Bearer mat_your_token_here"

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

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

{
  "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="
}

curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
  -H "Authorization: Bearer mat_your_token_here"

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

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

{
  "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="
}

Getting Started

Concepts

API Reference

Query Parameters

Response

​Query Parameters

​Response

Query Parameters

Response