# Poetry Foundation API: Search poems

> Finds poems matching a topic or occasion, or poems by a named poet, in Poetry Foundation search order. Older magazine poems without public text have no first two lines; untagged poems have no themes or occasions.

Unofficial. Not affiliated with or endorsed by Poetry Foundation.

- Page: https://fous.com/methods/poetryfoundation.org/search-poems
- Method: `poetryfoundation.org/search_poems`, version 1
- Website: poetryfoundation.org
- Returns: title, poet, first two lines, themes or occasions, poem link
- Effect: read (it gets data and changes nothing)
- Sign-in: none needed
- Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free
- Verified: Nov 2, 2026

## Inputs

| Field | Type | Required | In the run below | Description |
|---|---|---|---|---|
| `query` | string | yes | `"wedding"` | Topic, occasion, or poet name, for example grief, wedding, or Mary Oliver. |
| `max_results` | integer | no | `50` | Maximum number of poems to return, for example 20 (up to 50). Default 20. |

## Output

From a run on Oct 31, 2026, shortened. Its input:

```json
{
  "query": "wedding",
  "max_results": 50
}
```

Its output:

```json
{
  "poems": [
    {
      "poet": "Ross Gay",
      "title": "Wedding Poem",
      "poem_link": "https://www.poetryfoundation.org/poems/58761/wedding-poem",
      "first_two_lines": "Friends I am here to modestly report\nseeing in an orchard",
      "themes_or_occasions": [
        "Love",
        "Nature",
        "Animals"
      ]
    },
    {
      "poet": "Denise Levertov",
      "title": "Wedding-Ring",
      "poem_link": "https://www.poetryfoundation.org/poems/53080/wedding-ring",
      "first_two_lines": "My wedding-ring lies in a basket\nas if at the bottom of a well.",
      "themes_or_occasions": [
        "Social Commentaries",
        "Relationships",
        "Breakups & Separation"
      ]
    },
    {
      "poet": "Sidney Lanier",
      "title": "Wedding Hymn",
      "poem_link": "https://www.poetryfoundation.org/poems/50297/wedding-hymn",
      "first_two_lines": "Thou God, whose high, eternal Love\nIs the only blue sky of our life,",
      "themes_or_occasions": [
        "Love",
        "Religion",
        "Living"
      ]
    }
  ]
}
```

## Run it

From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output:

```bash
curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"poetryfoundation.org/search_poems","input":{"query":"wedding","max_results":50}}'
```

From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`.

## Ask your agent

- Find me about 10 poems about grief I could read at a memorial service
- What poems by Langston Hughes are on poetryfoundation.org? Give me titles and links.
- I need wedding poems for a toast — show me the first couple of lines of each so I can pick one
- Search Poetry Foundation for poems about the ocean, up to 50 results
- List poems by Emily Dickinson along with their themes

## Input schema

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Topic, occasion, or poet name, for example grief, wedding, or Mary Oliver."
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of poems to return, for example 20 (up to 50)."
    }
  }
}
```

## Output schema

```json
{
  "type": "object",
  "required": [
    "poems"
  ],
  "properties": {
    "poems": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "poet",
          "first_two_lines",
          "themes_or_occasions",
          "poem_link"
        ],
        "properties": {
          "poet": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": "string"
          },
          "poem_link": {
            "type": "string"
          },
          "first_two_lines": {
            "type": [
              "string",
              "null"
            ],
            "description": "The first two available lines, separated by a newline; null if the poem text is not published."
          },
          "themes_or_occasions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

## See more

- [Poetry Foundation API: Get poem by title](https://fous.com/methods/poetryfoundation.org/get-poem.md): Finds a poem on Poetry Foundation by title (optionally by poet) and returns its full public text, poet, printed source, publication year and subject tags.
- [Quran.com API: Search Quran verses](https://fous.com/methods/quran.com/search-quran.md): Finds Quran.com verses matching a word or topic, with Arabic text and a translation in the selected language, in Quran.com search order.
- [Britannica API: Search articles](https://fous.com/methods/britannica.com/search-articles.md): Searches Britannica for encyclopedia articles and returns their titles, short descriptions, article links and images when shown. Excludes other search formats such as videos, questions and stories.
- [Project Gutenberg API: Search free books](https://fous.com/methods/gutenberg.org/search-free-books.md): Finds free public-domain Project Gutenberg books by title, author or topic, with authors, languages, subjects, recent downloads, and reading and download links. Public-domain status is based on the United States.
- [Bible Gateway API: Search the Bible](https://fous.com/methods/biblegateway.com/search-bible.md): Finds Bible verses on Bible Gateway that contain the search words or relate to a topic. Returns the verse text and links in Bible order.
- [Open Library API: Search books](https://fous.com/methods/openlibrary.org/search-books.md): Finds Open Library books by search words, optionally narrowed by author and subject, sorted by relevance or publication age. Returns work-level results; free_online means at least one edition is marked public or borrowable, not that a loan is available now.
- [loc.gov API: Search Library of Congress collections](https://fous.com/methods/loc.gov/search-collections.md): Searches Library of Congress digital collections by keywords, material format and date range, in Library search relevance order. Rights notes may be unavailable for some records.
- [Substack API: Search newsletters](https://fous.com/methods/substack.com/search-newsletters.md): Finds public Substack newsletters matching a topic, in Substack's search order. Subscriber counts are null when Substack does not display one.
- [All Poetry Foundation methods](https://fous.com/methods/poetryfoundation.org.md)