Filtering requests - ButterCMS Docs

Blog Post filters

Filter blog posts using these built-in parameters:

Parameter	Description	Example
`author_slug`	Filter by author’s slug	`author_slug=john-doe`
`category_slug`	Filter by category slug	`category_slug=technology`
`tag_slug`	Filter by tag slug	`tag_slug=javascript`

Examples:

# Filter by author
/v2/posts/?author_slug=john-doe

# Filter by category
/v2/posts/?category_slug=technology

# Filter by tag
/v2/posts/?tag_slug=javascript

# Combine filters
/v2/posts/?author_slug=john-doe&category_slug=tutorials

# Full request with multiple filters
curl "https://api.buttercms.com/v2/posts/?author_slug=john-doe&category_slug=tutorials&page_size=10&auth_token=YOUR_TOKEN"

Page Type filters

Filter pages using field-based filtering and ordering: Field Filtering:

# Filter pages where the 'featured' field equals 'true'
/v2/pages/landing-page/?fields.featured=true

# Filter pages by category reference
/v2/pages/blog-post/?fields.category=technology

# Multiple field filters
/v2/pages/product/?fields.in_stock=true&fields.category=electronics

# Full request
curl "https://api.buttercms.com/v2/pages/landing-page/?fields.featured=true&auth_token=YOUR_TOKEN"

Ordering:

# Order by published date descending (newest first)
/v2/pages/landing-page/?order=-published

# Order by a custom field ascending
/v2/pages/landing-page/?order=title

# Full request
curl "https://api.buttercms.com/v2/pages/landing-page/?order=-published&auth_token=YOUR_TOKEN"

Ordering Options: You can order by page-level fields like published or updated, or by any content field of the Page Type. Prepend - for descending order (e.g., -published for newest first).

Collection filters

Filter collection items using dynamic field filtering:

# Filter collection by field
/v2/content/?keys=products&fields.category=software

# Filter by multiple fields
/v2/content/?keys=team-members&fields.department=engineering&fields.active=true

# Full request
curl "https://api.buttercms.com/v2/content/?keys=categories&fields.name=Technology&auth_token=YOUR_TOKEN"

JavaScript SDK:

// Filter collection items
const result = await butter.content.retrieve(['products'], {
  'fields.category': 'software',
  'fields.in_stock': true
});

Combining filters with pagination

For optimal performance, combine filtering with pagination to fetch exactly what you need:

const butter = Butter('YOUR_API_TOKEN');

// Fetch page 1 of tutorials by a specific author
const response = await butter.post.list({
  page: 1,
  page_size: 10,
  author_slug: 'john-doe',
  category_slug: 'tutorials',
  exclude_body: true
});

See Pagination for page-based and offset-based pagination options.

Pagination Caching strategies

​Blog Post filters

​Page Type filters

​Collection filters

​Combining filters with pagination

Blog Post filters

Page Type filters

Collection filters

Combining filters with pagination