# 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/workflows/the-new-york-times
- Handle: `@the-new-york-times`
- Category: [News](https://fous.com/workflows/category/news)
- Source website: https://nytimes.com
- Last verified: Sep 28, 2026
- Fous is not affiliated with The New York Times.

## Methods

### List best sellers

Operation `list_best_sellers`, version 1. 1 credit per call.

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 |  | Position on this list. |
| `books[].title` | string |  |  |
| `books[].author` | string or null |  |  |
| `books[].isbn_13` | string or null |  |  |
| `books[].buy_links` | array |  |  |
| `books[].page_link` | string |  | Link to this book on its Best Sellers page. |
| `books[].publisher` | string or null |  |  |
| `books[].description` | string or null |  |  |
| `books[].weeks_on_list` | integer or null |  | Number of issues on the list. |
| `books[].rank_last_week` | integer or null |  | 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 |  |  |
| `list_name` | string |  |  |
| `published_date` | string |  |  |

### List headlines

Operation `list_headlines`, version 1. 1 credit per call.

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 |  | Selected news section. |
| `stories[].summary` | string or null |  | Summary shown on the section page, if available. |
| `stories[].headline` | string |  | Headline as shown on the section page. |
| `stories[].image_url` | string or null |  | Image link shown with the story, if any. |
| `stories[].article_url` | string |  | The New York Times story link. |
| `stories[].published_at` | string or null |  | Publication date and time with timezone, if available. |

### Search news

Operation `search_news`, version 1. 1 credit per call.

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

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_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.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

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=120) 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.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_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);
```

Or describe the data in plain language: send `{"api":"@the-new-york-times","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## 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

### Is Fous affiliated with The New York Times?

No. Fous is not affiliated with The New York Times. This workflow reads the public nytimes.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. 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; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check 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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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 workflows](https://fous.com/workflows/category/news)