# The New York Times API

> The New York Times workflow returns headlines, article search results, and best seller lists, available as a workflow and API.

The New York Times (NYT) headline workflow reads a chosen section and returns headlines, summaries, authors, links, and available publication dates. Search news finds article headlines and summaries matching required keywords, with optional date range, sorting, and page inputs. List best sellers returns books for a required list name and the latest issue or a date within a week.

- Page: https://fous.com/tools/the-new-york-times
- Handle: `@the-new-york-times`
- Category: [News](https://fous.com/tools/category/news)
- Source website: https://nytimes.com
- Last verified: Sep 28, 2026

## Methods

### List best sellers

Operation `list_best_sellers`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a New York Times Best Sellers list by name for the latest issue or a date within a week. Monthly lists use their issue month.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `week` | string | no | `"2025-03-25"` | Any day in the requested list week, for example 2025-03-25. Leave out for the latest issue. |
| `list_name` | string | yes | `"Hardcover Fiction"` | The list name in plain words, such as Hardcover Fiction or Young Adult Hardcover. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "list_name"
  ],
  "properties": {
    "week": {
      "type": "string",
      "format": "date",
      "examples": [
        "2025-03-25"
      ],
      "description": "Any day in the requested list week, for example 2025-03-25. Leave out for the latest issue."
    },
    "list_name": {
      "type": "string",
      "examples": [
        "Hardcover Fiction"
      ],
      "description": "The list name in plain words, such as Hardcover Fiction or Young Adult Hardcover."
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "list_name": "Hardcover Fiction"
    },
    {
      "week": "2025-03-25",
      "list_name": "Combined Print & E-Book Nonfiction"
    },
    {
      "week": "2025-03-30",
      "list_name": "Young Adult Hardcover"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `books` | array |  |  |
| `books[].rank` | integer | `1` | Position on this list. |
| `books[].title` | string | `"DEAD BEAT"` |  |
| `books[].author` | string or null | `"Leigh Bardugo"` |  |
| `books[].isbn_13` | string or null | `"9781250884312"` |  |
| `books[].buy_links` | array |  |  |
| `books[].page_link` | string | `"https://www.nytimes.com/books/best-sellers/2026/10/04/hardcover-fiction/#QmVzdFNlbGxlckJvb2s6LTk3ODEyNTA4ODQzMTI="` | Link to this book on its Best Sellers page. |
| `books[].publisher` | string or null | `"Flatiron"` |  |
| `books[].description` | string or null | `"The third book in the Ninth House series. Alex and her allies battle demons found in New Haven and on the Yale campus."` |  |
| `books[].weeks_on_list` | integer or null | `1` | Number of issues on the list. |
| `books[].rank_last_week` | integer or null | `6` | Rank on the preceding list, or null if not ranked then. |
| `books[].book_review_link` | string or null |  |  |
| `books[].cover_image_link` | string or null | `"https://static01.nyt.com/bestsellers/images/9781250884312.jpg"` |  |
| `list_name` | string | `"Hardcover Fiction"` |  |
| `published_date` | string | `"2026-10-04"` |  |

**Example input**

```json
{
  "list_name": "Hardcover Fiction"
}
```

**Example output**

```json
{
  "books": [
    {
      "rank": 1,
      "title": "DEAD BEAT",
      "author": "Leigh Bardugo",
      "isbn_13": "9781250884312",
      "buy_links": [
        {
          "link": "https://www.amazon.com/dp/1250884314?tag=thenewyorktim-20",
          "store_name": "Amazon"
        },
        {
          "link": "https://goto.applebooks.apple/9781250884312?at=10lIEQ",
          "store_name": "Apple Books"
        }
      ],
      "page_link": "https://www.nytimes.com/books/best-sellers/2026/10/04/hardcover-fiction/#QmVzdFNlbGxlckJvb2s6LTk3ODEyNTA4ODQzMTI=",
      "publisher": "Flatiron",
      "description": "The third book in the Ninth House series. Alex and her allies battle demons found in New Haven and on the Yale campus.",
      "weeks_on_list": 1,
      "rank_last_week": null,
      "book_review_link": null,
      "cover_image_link": "https://static01.nyt.com/bestsellers/images/9781250884312.jpg"
    },
    {
      "rank": 2,
      "title": "HOLLOW BONES",
      "author": "Jodi Picoult",
      "isbn_13": "9780593726259",
      "buy_links": [
        {
          "link": "https://www.amazon.com/dp/0593726251?tag=thenewyorktim-20",
          "store_name": "Amazon"
        },
        {
          "link": "https://goto.applebooks.apple/9780593726259?at=10lIEQ",
          "store_name": "Apple Books"
        }
      ],
      "page_link": "https://www.nytimes.com/books/best-sellers/2026/10/04/hardcover-fiction/#QmVzdFNlbGxlckJvb2s6LTk3ODA1OTM3MjYyNTk=",
      "publisher": "Ballantine",
      "description": "A woman who runs the Rhode Island Department for Emergency Preparedness and her husband, who is a police polygraph expert, face a crisis in their marriage.",
      "weeks_on_list": 1,
      "rank_last_week": null,
      "book_review_link": null,
      "cover_image_link": "https://static01.nyt.com/bestsellers/images/9780593726259.jpg"
    }
  ],
  "list_name": "Hardcover Fiction",
  "published_date": "2026-10-04"
}
```

### List headlines

Operation `list_headlines`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

List current New York Times headlines and summaries in the order shown on a chosen section page. Video-only items, ads and promotions are excluded; dates may be unavailable.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `section` | string | no | `"top stories"` | News section to read, for example world. |
| `max_results` | integer | no | `20` | Most stories to return, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "section": {
      "enum": [
        "top stories",
        "world",
        "U.S.",
        "politics",
        "business",
        "technology",
        "opinion",
        "arts",
        "science"
      ],
      "type": "string",
      "default": "top stories",
      "description": "News section to read, for example world.",
      "examples": [
        "top stories",
        "world",
        "politics"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Most stories to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        20,
        50
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "section": "top stories",
      "max_results": 20
    },
    {
      "section": "world",
      "max_results": 20
    },
    {
      "section": "politics",
      "max_results": 50
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `stories` | array |  | News stories in the section page order. |
| `stories[].authors` | array |  | Named writers, when available. |
| `stories[].section` | string | `"top stories"` | Selected news section. |
| `stories[].summary` | string or null | `"Criminal hackers stole personal data involving potentially tens of thousands of former and current employees, leaving t` | Summary shown on the section page, if available. |
| `stories[].headline` | string | `"Embarrassing Breach at F.B.I. Fuels Fears of Harm to Its Employees"` | Headline as shown on the section page. |
| `stories[].image_url` | string or null | `"https://static01.nyt.com/images/2026/09/28/multimedia/28dc-fbi-top-hgcb/28dc-fbi-top-hgcb-mediumSquareAt3X.jpg"` | Image link shown with the story, if any. |
| `stories[].article_url` | string | `"https://www.nytimes.com/2026/09/28/us/politics/fbi-shinyhunters-damage.html"` | The New York Times story link. |
| `stories[].published_at` | string or null | `"2026-09-28T21:36:07+00:00"` | Publication date and time with timezone, if available. |

**Example input**

```json
{
  "section": "top stories",
  "max_results": 20
}
```

**Example output**

```json
{
  "stories": [
    {
      "authors": [
        "Dustin Volz",
        "Alan Feuer",
        "Charlie Savage"
      ],
      "section": "top stories",
      "summary": "Criminal hackers stole personal data involving potentially tens of thousands of former and current employees, leaving the bureau rushing to protect its staff.",
      "headline": "Embarrassing Breach at F.B.I. Fuels Fears of Harm to Its Employees",
      "image_url": "https://static01.nyt.com/images/2026/09/28/multimedia/28dc-fbi-top-hgcb/28dc-fbi-top-hgcb-mediumSquareAt3X.jpg",
      "article_url": "https://www.nytimes.com/2026/09/28/us/politics/fbi-shinyhunters-damage.html",
      "published_at": "2026-09-28T21:36:07+00:00"
    },
    {
      "authors": [
        "Matthew C. Klein"
      ],
      "section": "top stories",
      "summary": "A shift in fuel economy rules, Republicans’ major ad blitz and a phone-free concert.",
      "headline": "Catch Up on Today’s Biggest Stories",
      "image_url": "https://static01.nyt.com/images/2026/09/28/multimedia/28evening-nl-top1/28evening-nl-top1-mediumSquareAt3X.jpg",
      "article_url": "https://www.nytimes.com/2026/09/28/briefing/trump-sharply-scales-back-fuel-economy-rules.html",
      "published_at": "2026-09-28T22:05:33+00:00"
    },
    {
      "authors": [
        "Kim Barker",
        "Maria Varenikova",
        "Oleksandra Mykolyshyn"
      ],
      "section": "top stories",
      "summary": "A Russian jet-powered drone hit Ukraine’s National Academy of Sciences, the source of almost all of the country’s major scientific discoveries.",
      "headline": "Fire, Smoke and Desperation After a Strike in the Heart of Kyiv",
      "image_url": "https://static01.nyt.com/images/2026/09/28/multimedia/28ukraine-strike-01-fmzj/28ukraine-strike-01-fmzj-mediumSquareAt3X.jpg",
      "article_url": "https://www.nytimes.com/2026/09/28/world/europe/urkaine-drone-attack-kyiv-academy-sciences.html",
      "published_at": "2026-09-28T19:33:55+00:00"
    }
  ]
}
```

### Search news

Operation `search_news`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Search New York Times article headlines and summaries by keyword and return matching dates, authors, sections and links. Public listings only; excludes full story text and The Athletic.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `page` | integer | no | `1` | Page number starting at 1, for example 2. |
| `sort` | string | no | `"most_relevant"` | Order results by newest or most relevant, for example newest. |
| `query` | string | yes | `"Tesla"` | Words to search in New York Times articles, for example Tesla. |
| `to_date` | string | no | `"2026-09-27"` | Latest publication date, inclusive, for example 2026-09-28. |
| `from_date` | string | no | `"2026-09-01"` | Earliest publication date, inclusive, for example 2026-09-01. |
| `max_results` | integer | no | `10` | Maximum articles on this page, up to 50, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Page number starting at 1, for example 2.",
      "x-fous-developer": true,
      "examples": [
        1,
        2
      ]
    },
    "sort": {
      "enum": [
        "newest",
        "most_relevant"
      ],
      "type": "string",
      "default": "newest",
      "description": "Order results by newest or most relevant, for example newest.",
      "examples": [
        "most_relevant",
        "newest"
      ]
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Words to search in New York Times articles, for example Tesla.",
      "examples": [
        "Tesla",
        "climate change",
        "xyzzqnotaword90387145"
      ]
    },
    "to_date": {
      "type": "string",
      "format": "date",
      "description": "Latest publication date, inclusive, for example 2026-09-28.",
      "examples": [
        "2026-09-27"
      ]
    },
    "from_date": {
      "type": "string",
      "format": "date",
      "description": "Earliest publication date, inclusive, for example 2026-09-01.",
      "examples": [
        "2026-09-01"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum articles on this page, up to 50, for example 20.",
      "x-fous-developer": true,
      "examples": [
        10,
        20
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "page": 1,
      "sort": "most_relevant",
      "query": "Tesla",
      "to_date": "2026-09-27",
      "from_date": "2026-09-01",
      "max_results": 10
    },
    {
      "query": "Tesla"
    },
    {
      "page": 2,
      "sort": "most_relevant",
      "query": "Tesla",
      "max_results": 10
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `articles` | array |  | New York Times articles matching the search. |
| `articles[].authors` | array |  |  |
| `articles[].section` | string or null | `"Business"` |  |
| `articles[].summary` | string or null | `"The new Cybercab embodies Elon Musk’s vision of cars that drive themselves, but it is not clear when the vehicle will b` |  |
| `articles[].headline` | string | `"Tesla Begins Offering Rides in a Car Without a Steering Wheel"` |  |
| `articles[].article_link` | string | `"https://www.nytimes.com/2026/09/03/business/tesla-cybercab-robotaxi-rides.html"` |  |
| `articles[].published_at` | string | `"2026-09-03T22:12:46+00:00"` |  |

**Example input**

```json
{
  "page": 1,
  "sort": "most_relevant",
  "query": "Tesla",
  "to_date": "2026-09-27",
  "from_date": "2026-09-01",
  "max_results": 10
}
```

**Example output**

```json
{
  "articles": [
    {
      "authors": [
        "Jack Ewing"
      ],
      "section": "Business",
      "summary": "The new Cybercab embodies Elon Musk’s vision of cars that drive themselves, but it is not clear when the vehicle will be widely available.",
      "headline": "Tesla Begins Offering Rides in a Car Without a Steering Wheel",
      "article_link": "https://www.nytimes.com/2026/09/03/business/tesla-cybercab-robotaxi-rides.html",
      "published_at": "2026-09-03T22:12:46+00:00"
    },
    {
      "authors": [
        "Jack Ewing"
      ],
      "section": "Business",
      "summary": "The National Highway Traffic Safety Administration said it would examine whether the company’s new self-driving taxi, which has no steering wheel, meets federal auto regulations.",
      "headline": "Tesla’s Cybercab Is Being Investigated by Federal Regulators",
      "article_link": "https://www.nytimes.com/2026/09/04/business/tesla-cybercab-nhtsa-investigation.html",
      "published_at": "2026-09-04T13:19:46+00:00"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@the-new-york-times",
  "visibility": "public",
  "operation": "list_best_sellers",
  "version": 1,
  "input": {
    "list_name": "Hardcover Fiction"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@the-new-york-times\",\n  \"visibility\": \"public\",\n  \"operation\": \"list_best_sellers\",\n  \"version\": 1,\n  \"input\": {\n    \"list_name\": \"Hardcover Fiction\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@the-new-york-times",
  "visibility": "public",
  "operation": "list_best_sellers",
  "version": 1,
  "input": {
    "list_name": "Hardcover Fiction"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/the-new-york-times`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `list_best_sellers`: List best sellers. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_headlines`: List headlines. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_news`: Search news. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-the-new-york-times https://api.fous.com/mcp/tools/the-new-york-times --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Track headlines across selected news sections.
- Find articles about a keyword within a date range.
- Compare article coverage by section and publication date.
- Monitor book rankings across best seller lists.
- Review book authors, publishers, and time on a list.

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this The New York Times tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a The New York Times account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from nytimes.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 28, 2026.

### What headlines appear in a news section?

List headlines returns stories in the order shown on the chosen section page.

### Which articles match a keyword and date range?

Search news returns matching article headlines and summaries, with dates, authors, sections, and links.

### What books are on a best seller list?

List best sellers returns books and their ranks for the specified list name and issue.

## Related

- [The Wall Street Journal API](https://fous.com/tools/the-wall-street-journal.md): The Wall Street Journal provides news-section headlines and searchable public article headlines and summaries, with available story details and publication dates for search filtering.
- [NPR API](https://fous.com/tools/npr.md): NPR returns displayed section headlines, searchable articles with summaries and publication details, and available article text; date-filtered searches may miss older stories edited much later.
- [Yahoo News API](https://fous.com/tools/yahoo-news.md): Yahoo News provides section headlines and searchable articles, plus public article text and details; health has no public stories, and search covers a limited results window.
- [AP News API](https://fous.com/tools/ap-news.md): AP News provides reporting, up to 50 public-page headlines, searchable articles visible in its search, and full text when accessible.
- [Fox News API](https://fous.com/tools/fox-news.md): Fox News returns section-page headlines, keyword-matched articles among up to 100 available results, and readable article text, including the latest live-blog updates.
- [CNN API](https://fous.com/tools/cnn.md): CNN provides section-page headlines and searchable public articles, plus article text; subscriber stories show only a brief public preview, and live blogs include entries.
- [The Verge API](https://fous.com/tools/the-verge.md): The Verge provides technology, science, entertainment, and policy headlines and searchable articles, including public stories and older archives, with search limited to the first 100 matches.
- [BBC News API](https://fous.com/tools/bbc-news.md): BBC News returns section-ordered headlines, searchable articles with dates, authors and sections (filters/newest sorting cover 180 matches), and article text with available latest live entries.
- [All News tools](https://fous.com/tools/category/news)