What Are Story Data Fields?

When you retrieve stories from Hacker News through the MCP server, each story comes with a structured set of data fields that provide comprehensive information about the submission. Understanding these fields helps you extract exactly the information you need and interpret the data correctly.

Core Story Fields

Every story includes several essential fields:

ID - A unique numeric identifier for the story. This ID is permanent and can be used to reference the specific story in future queries or to construct direct links to the Hacker News page.

Title - The headline or title of the submission as entered by the user who posted it.

URL - The web address of the linked content. For text posts (Ask HN, Show HN, or discussion posts), this field may be absent since the discussion happens directly on Hacker News.

Score - The number of upvotes the story has received, reflecting community interest and approval. Scores change over time as users continue to vote.

Author (by) - The username of the Hacker News member who submitted the story.

Time - A Unix timestamp indicating when the story was submitted. This helps you determine how recent the content is and track submission patterns.

Descendants - The total count of comments in the discussion thread, including all nested replies. This gives you a quick sense of how much conversation the story has generated.

Understanding Story Types

Stories on Hacker News fall into several categories. Standard stories link to external content—articles, papers, or projects. "Ask HN" posts are questions posed to the community. "Show HN" submissions showcase projects or creations. Text posts contain discussion prompts without external links. The story structure accommodates all these types, though certain fields like URL may be empty for text-based submissions.

Working with Story Collections

When you request lists like "top stories" or "new stories," you'll receive an ordered array of story IDs. These collections represent different views into Hacker News content. Top stories are those currently featured on the front page based on score and recency. New stories show the latest submissions regardless of score. Best stories highlight content that has performed exceptionally well over time.

To get full details about stories in these collections, you'll need to request each story individually by its ID. This two-step approach—getting a list of IDs, then fetching details—is how Hacker News structures its data and allows you to control how much information you retrieve.

Practical Tips

When analyzing stories, remember that scores and comment counts are dynamic and reflect the state at query time. For time-sensitive analysis, note the submission timestamp to understand how quickly stories are gaining traction. Missing URLs indicate text posts where the discussion is the primary content rather than a linked article.