Ghost Content API Bug Report: Excerpt Field Filtering Issue

Bugs
1

Issue Summary

When using the Ghost Content API, filtering with the contains operator (~) on the excerpt field returns a “Request not understood error”, while the same syntax works correctly for other fields like title.

Expected Behavior

According to the NQL documentation, it should be possible to use the contains operator (~) on the excerpt field, allowing queries like excerpt:~'how' to find posts where the excerpt contains the word “how”.

Actual Behavior

When attempting to filter using excerpt:~'how', the API returns:

Error [BadRequestError]: Request not understood error, cannot list posts.
context: 'Could not understand request.',
type: 'BadRequestError',
code: 'ER_BAD_FIELD_ERROR'

The same syntax works correctly for other fields like title.

Steps to Reproduce

  1. Use the Ghost Content API client to query posts
  2. Add a filter for excerpt:~'any_term'
  3. Observe the BadRequestError response

Code Example

const ghostClient = new GhostContentAPI({
  url: 'https://your-ghost-site.com',
  key: 'your-content-api-key',
  version: 'v5.0'
});

// This causes the error
const searchFilter = `excerpt:~'how'`;

// Execute search query against Ghost API
const searchResponse = await ghostClient.posts.browse({
  limit: 9,
  page: 1,
  filter: searchFilter,
  include: ["tags", "authors"],
  order: "published_at DESC",
});

Environment

  • Ghost Version: v5.119 (based on content-version header)
  • Using official Ghost Content SDK/1.11.22
  • Client using TypeScript with Astro

Workarounds Attempted

  1. Tried different filter syntax variations with the same result
  2. Filtering on title field works correctly
  3. Manual URL encoding doesn’t resolve the issue

Impact

This bug prevents implementing search functionality across post excerpts, limiting search to only title fields, which significantly reduces search effectiveness and user experience.

Additional Context

The issue might be specific to how the excerpt field is stored or indexed in the database, as other text fields like title work correctly with the contains operator.

2

Does it work if you switch to custom_excerpt?

3

excerpt is a generated API field so it’s not searchable at the database level. You’d need to filter against custom_excerpt or plaintext as @Cathy_Sarisky suggests above.

That said, it sounds like you’re attempting to implement full text search by pushing field filters beyond what they are intended for, you may quickly run into performance issues with that approach. I would suggest looking at a more use-case optimised search implementation if you have a large or growing site.

2 Likes