Skip to main content
Marble API provides powerful filtering options to retrieve exactly the content you need. Filters are applied using query parameters and can be combined for precise content selection.

​
How Filtering Works

When you request a list of posts, you can include or exclude content based on:
  • Categories - Filter by the post’s category (a post belongs to one category)
  • Tags - Filter by the post’s tags (a post can have multiple tags)
  • Featured status - Filter by whether a post is featured
  • Search queries - Search for matches in title and content
All filters are combined using AND logic. When multiple filters are applied, posts must match all conditions to be included in the results.

​
Filter Parameters

​
categories
string
Comma-separated list of category slugs. Posts must belong to one of the specified categories. Example: tech,news
​
excludeCategories
string
Comma-separated list of category slugs to exclude. Posts in these categories will be omitted from results. Example: changelog,legal
​
tags
string
Comma-separated list of tag slugs. Posts must have at least one of the specified tags. Example: javascript,react
​
excludeTags
string
Comma-separated list of tag slugs to exclude. Posts with any of these tags will be omitted. Example: outdated,draft
​
query
string
Search term to filter by title and content. Example: nextjs
​
order
string
default:"desc"
Sort order by publishedAt. Options: asc or desc
​
featured
string
Filter by featured status. Options: true or false

​
SDK Examples

Get all posts in the “tutorials” category:
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

const result = await marble.posts.list({
  categories: ["tutorials"],
});

for await (const page of result) {
  console.log(page.posts);
}

​
Filter Behavior

AND Logic: All specified filters are applied together. A post must satisfy every condition to appear in results.

​
Understanding Filter Precedence

When using both include and exclude filters, they work together—not against each other:
Filter CombinationResult
categories=techPosts in “tech” category
excludeTags=outdatedPosts without “outdated” tag
categories=tech&excludeTags=outdatedPosts in “tech” AND without “outdated” tag
Important: If a post is in the “tech” category but has the “outdated” tag, it will be excluded when using categories=tech&excludeTags=outdated. Exclude filters take effect regardless of category matches.

​
Include vs Exclude Logic

Posts must belong to one of the specified categories:
?categories=tech,news
Returns posts in “tech” OR “news” categories.
Posts must not belong to any excluded category:
?excludeCategories=legal,changelog
Returns all posts except those in “legal” or “changelog”.
Posts must have at least one of the specified tags:
?tags=react,nextjs
Returns posts tagged with “react” OR “nextjs” (or both).
Posts must have none of the excluded tags:
?excludeTags=outdated
Returns posts that do not have the “outdated” tag.

​
Search Queries

Use the query parameter to search for matches in post titles and content: 
import { Marble } from "@usemarble/sdk";

const marble = new Marble({
  apiKey: process.env["MARBLE_API_KEY"] ?? "",
});

const result = await marble.posts.list({
  query: "getting started",
});

for await (const page of result) {
  console.log(page.posts);
}
Combine search with category filters for targeted results: ?categories=tutorials&query=authentication

​
Common Use Cases

Exclude system pages like legal and changelog:
await marble.posts.list({
  excludeCategories: ["legal", "changelog"],
});

​
Best Practices

Use excludes for “everything except”: When you want all content except a few categories, use excludeCategories instead of listing every category you want.
Combine with pagination: Filtering works seamlessly with pagination. Apply filters first, then paginate through the filtered results.
Filter order doesn’t matter: The API applies all filters together regardless of the order you specify them in the query string.
Watch your rate limits: Each search request counts against your rate limit. For real-time “search as you type” experiences, fetch your posts once and filter them client-side instead of making a new API request on every keystroke.