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

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

​
status
string
default:"all"
Filter by item status. Comma-separated for multiple: queue,archive. Values: inbox, queue, archive, or all.
​
order
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.
​
is_favorite
boolean
Filter to favorited items only.
​
tag
string
Filter to items with a specific tag ID. Comma-separated for multiple: tag_n5j2x,tag_k3m9p (returns items matching any of the tags).
​
content_type
string
Filter by content type. Comma-separated for multiple: article,podcast. Values: article, video, podcast, pdf, tweet, newsletter.
​
updated_since
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.
​
limit
integer
default:25
Number of items per page. Min 1, max 100.
​
cursor
string
Cursor for the next page of results. Obtained from next_cursor in a previous response.

​
Response

​
object
string
required
Always "list".
​
results
array
required
Array of item objects. See Get Item for the full item schema.
​
has_more
boolean
required
Whether there are more results after this page.
​
next_cursor
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"

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