What is Story Data?

Stories are the fundamental content type on Hacker News, representing submissions shared by users—whether links to external articles, Ask HN discussions, Show HN project announcements, or job postings. When you retrieve stories through the Hacker News MCP Server, you receive structured data containing all the information needed to understand and work with each submission.

Core Story Fields

Identification and Basic Info

Each story has a unique id that serves as its permanent identifier across the Hacker News platform. You'll use this ID to retrieve specific stories or reference them when accessing related comments. The type field indicates what kind of item you're working with—typically "story" for standard submissions, though you may also encounter "job" or "poll" types.

Content and Metadata

The title contains the story's headline as submitted by the user. This is typically the article title or a user-written description for text posts. The url field provides the link to the external content, though this may be absent for Ask HN posts or other text-only submissions.

For text posts, the text field contains the actual content written by the submitter. This field uses HTML formatting, so you may need to handle markup when displaying or processing it.

Community Engagement Metrics

The score indicates how many upvotes the story has received, reflecting community interest and approval. Higher scores generally indicate content the community found valuable or interesting. The descendants field tells you the total number of comments in the discussion, including nested replies, giving you a sense of how much conversation the story generated.

Author and Timing

The by field contains the username of the person who submitted the story, allowing you to track submissions by specific users or research the submitter's background. The time field is a Unix timestamp indicating when the story was submitted, essential for understanding recency and tracking trends over time.

Comment Structure

The kids field contains an array of comment IDs representing direct replies to the story. These are top-level comments in the discussion thread. You can retrieve each comment individually using its ID to build out the full conversation tree.

Working With Story Data

When you request stories through natural language queries, the server automatically retrieves and presents these fields in an organized format. Understanding this structure helps you ask more targeted questions and better interpret the results, whether you're analyzing trends, researching topics, or monitoring discussions.