Filtering

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

SDK Examples

Filter by Category
Exclude Categories
Filter by Tags
Combined Filters
Featured Posts

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);
}

Get all posts except those in “changelog” or “legal”:

import { Marble } from "@usemarble/sdk";

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

const result = await marble.posts.list({
  excludeCategories: ["changelog", "legal"],
});

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

Get posts tagged with “javascript” or “typescript”:

import { Marble } from "@usemarble/sdk";

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

const result = await marble.posts.list({
  tags: ["javascript", "typescript"],
});

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

Get posts in “tutorials” but exclude outdated content:

import { Marble } from "@usemarble/sdk";

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

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

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

Get only featured posts:

import { Marble } from "@usemarble/sdk";

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

const result = await marble.posts.list({
  featured: "true",
});

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 Combination	Result
`categories=tech`	Posts in “tech” category
`excludeTags=outdated`	Posts without “outdated” tag
`categories=tech&excludeTags=outdated`	Posts 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

Categories (include)

Posts must belong to one of the specified categories:

?categories=tech,news

Returns posts in “tech” OR “news” categories.

Categories (exclude)

Posts must not belong to any excluded category:

?excludeCategories=legal,changelog

Returns all posts except those in “legal” or “changelog”.

Tags (include)

Posts must have at least one of the specified tags:

?tags=react,nextjs

Returns posts tagged with “react” OR “nextjs” (or both).

Tags (exclude)

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

Blog Posts Only
Featured Content
Fresh Content
Topic Deep Dive

Exclude system pages like legal and changelog:

await marble.posts.list({
  excludeCategories: ["legal", "changelog"],
});

Get only featured posts:

await marble.posts.list({
  featured: "true",
});

Exclude outdated posts:

await marble.posts.list({
  excludeTags: ["outdated", "archived"],
});

Category + search combo:

await marble.posts.list({
  categories: ["tutorials"],
  query: "react hooks",
});

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.

Getting Started

Posts

Authors

Categories

Tags

Media

How Filtering Works

Filter Parameters

SDK Examples

Filter Behavior

Understanding Filter Precedence

Include vs Exclude Logic

Search Queries

Common Use Cases

Best Practices

​How Filtering Works

​Filter Parameters

​SDK Examples

​Filter Behavior

​Understanding Filter Precedence

​Include vs Exclude Logic

​Search Queries

​Common Use Cases

​Best Practices

How Filtering Works

Filter Parameters

SDK Examples

Filter Behavior

Understanding Filter Precedence

Include vs Exclude Logic

Search Queries

Common Use Cases

Best Practices