Get Item

GET

items

{id}

curl https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer mat_your_token_here"

curl "https://api.getmatter.com/public/v1/items/itm_r9f3a?include=markdown" \
  -H "Authorization: Bearer mat_your_token_here"

response = requests.get(
    "https://api.getmatter.com/public/v1/items/itm_r9f3a",
    headers={"Authorization": f"Bearer {token}"},
    params={"include": "markdown"}
)
item = response.json()

{
  "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",
  "excerpt": "Paul Graham explores what it takes to do great work...",
  "library_position": 58974321000,
  "inbox_position": null,
  "tags": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays"
    }
  ],
  "updated_at": "2026-03-30T19:15:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "No item found with ID itm_abc123."
  }
}

Path Parameters

string

required

The item ID. Example: itm_r9f3a.

Query Parameters

string

Comma-separated list of additional fields to include. Currently supported: markdown.When markdown is included, the response adds a markdown field with the parsed article body. These requests count against the content rate limit (20/min).

Response

string

required

Always "item".

string

required

The item ID.

string

required

The item’s title.

string

required

The original URL of the item.

string

The source website name.

object

The item’s author, if known.

Show author properties

string

Always "author".

string

Author ID.

string

Author display name.

string

required

One of inbox, queue, or archive.

string

required

Content extraction status. One of processing, completed, or failed. See Save Item for details.

boolean

required

Whether the item is favorited.

string

required

One of article, video, podcast, pdf, tweet, newsletter.

integer

Estimated word count. null for non-text content.

number

required

Reading progress as a float from 0.0 to 1.0.

string

URL of the item’s hero image, if available.

string

The parsed article body as markdown. Only included when ?include=markdown is set. null if the item hasn’t been processed yet.

string

Short excerpt or description of the item, if available.

integer

The item’s position in the library (queue/archive). Non-null when the item has a library entry. Higher values are closer to the top. Use this to recreate library order locally.

integer

The item’s 0-based index in the inbox feed. Non-null when the item is in the inbox. Lower values are closer to the top. Use this to recreate inbox order locally.

array

required

Tags applied to this item.

Show tag properties

string

Always "tag".

string

Tag ID.

string

Tag name.

integer

Number of items with this tag.

string

ISO 8601 timestamp.

string

required

ISO 8601 timestamp of the last change to this item or its associated data (status, reading progress, favorites, tags, annotations, or content re-extraction). For inbox items with no interactions, this is the time the item appeared in your inbox.

curl https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer mat_your_token_here"

curl "https://api.getmatter.com/public/v1/items/itm_r9f3a?include=markdown" \
  -H "Authorization: Bearer mat_your_token_here"

response = requests.get(
    "https://api.getmatter.com/public/v1/items/itm_r9f3a",
    headers={"Authorization": f"Bearer {token}"},
    params={"include": "markdown"}
)
item = response.json()

{
  "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",
  "excerpt": "Paul Graham explores what it takes to do great work...",
  "library_position": 58974321000,
  "inbox_position": null,
  "tags": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays"
    }
  ],
  "updated_at": "2026-03-30T19:15:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "No item found with ID itm_abc123."
  }
}

curl https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer mat_your_token_here"

curl "https://api.getmatter.com/public/v1/items/itm_r9f3a?include=markdown" \
  -H "Authorization: Bearer mat_your_token_here"

response = requests.get(
    "https://api.getmatter.com/public/v1/items/itm_r9f3a",
    headers={"Authorization": f"Bearer {token}"},
    params={"include": "markdown"}
)
item = response.json()

{
  "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",
  "excerpt": "Paul Graham explores what it takes to do great work...",
  "library_position": 58974321000,
  "inbox_position": null,
  "tags": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays"
    }
  ],
  "updated_at": "2026-03-30T19:15:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "No item found with ID itm_abc123."
  }
}

Getting Started

Concepts

API Reference

Path Parameters

Query Parameters

Response

​Path Parameters

​Query Parameters

​Response

Path Parameters

Query Parameters

Response