What is Story Data?

When you retrieve stories from Hacker News through this MCP server, each story comes with a standardized set of fields that provide comprehensive information about the submission. Understanding these fields helps you effectively work with and analyze Hacker News content.

Core Story Fields

Every story object contains several essential pieces of information:

ID: A unique numeric identifier for the story. This ID is permanent and can be used to retrieve the specific story or its comments at any time. You'll need this ID when you want to access a story's comment thread.

Title: The headline or title of the submission as written by the person who posted it. This is what appears in story listings and feeds.

URL: The link to the external content being shared. This field may be empty for "Ask HN" or "Show HN" posts that are text-only discussions without external links.

Score: The number of upvotes the story has received from the community. Higher scores generally indicate greater community interest or approval. Scores change over time as more users vote.

Author (by): The username of the person who submitted the story. You can use this to look up the submitter's profile or track submissions from specific users.

Time: A Unix timestamp indicating when the story was submitted. This helps you understand the recency of content and track when discussions began.

Descendants: The total number of comments in the story's discussion thread, including all replies and nested comments. This gives you a quick sense of how much conversation the story has generated.

Special Story Types

Some stories have unique characteristics:

Text Posts: Stories without URLs are self-contained discussions. These include "Ask HN" questions, "Show HN" project announcements, and community polls. For these submissions, the main content is in the story's text field rather than an external link.

Deleted or Dead Stories: Stories may be flagged as deleted or dead if they've been removed by moderators or killed by community flags. These fields help you filter out content that's no longer active.

Working With Story Data

When you request stories through the server, you might retrieve them as lists (like top stories or new stories) or as individual items. List endpoints typically return arrays of story IDs, which you can then query individually for complete details. This two-step approach is how Hacker News structures its API, allowing efficient retrieval of story feeds without overwhelming data transfer.

Understanding these fields enables you to filter, sort, and analyze Hacker News content effectively, whether you're tracking trending topics, researching discussions, or monitoring community engagement.