Feed Builder & feed

This guide provides comprehensive documentation for all Feed Builder features, advanced usage patterns, and integration details. If you're new to Feed Builder, start with the Feed Builder Quick Start to get up and running quickly.

Killer Features

Feed_id

For each feed that you create through the API or feed builder you obtain a feed_id. This is a feed object that will make it easy to integrate in your app's code and update separately. You will also be able to compose different feed_ids together.

Promoted Content and Feed Mixing

With the promotion feature at Step 4 of the feed building process, you can mix different feed_ids together allowing you to have a high degree of control over what your users and being able to experiment quickly.

You can also introduce promotion items guaranteed to appear in users' feeds. Perfect for marketing campaigns, featured content, or sponsored posts.

Re-Ranking

In order to better personalize what your users see, you have scoring functions available in the feed builder at Step 2: Candidate Generation. These will let you rank the candidates generated at Step 1: Candidate Generation based on their interest, social graph, or the topics you're looking to put forward on your app.

Linear Boost Scoring

Build custom ranking algorithms with Linear Boost, our most advanced scoring option. Instead of choosing a single pre-built algorithm, you can create weighted combinations of ranking features. Boost specific AI labels (like crypto topics, tech news, or creative content), combine interest scores with trending signals, or emphasize social proof—all with precise weight controls. Perfect for A/B testing different ranking strategies and fine-tuning what matters most for your audience.

Candidate Sources and Candidate Generation

Switch between an increasing amount of candidate sources: Farcaster, Zora, Polymarket (coming soon) and generate candidates using a powerful set of filters:

Content Filters:

AI Labels - Filter by topics (business, tech, gaming, crypto, etc.), sentiment (positive, negative, neutral), emotions (joy, love, optimism), and moderation labels
Channels - Include or exclude specific Farcaster channels to focus on niche communities
Authors - Curate content from specific creators or exclude certain authors
Publication Types - Filter by media type: images, videos, audio, or mini-apps with advanced video filters (duration, orientation, language)
Keywords - Include or exclude posts containing specific keywords or phrases
Languages - Target content in 18+ languages including English, Spanish, Chinese, Japanese, and more
Geo Locations - Filter content by geographic location based on where posts were created
Embed Domains - Include posts that embed content from specific domains (e.g., Mirror, Paragraph)

Engagement Filters:

Like Count - Set minimum or maximum thresholds for post engagement
Comment Count - Filter by discussion activity levels
Share Count - Target viral content or emerging posts
Character Length - Control post length from short-form to long-form content

Time-Based Filters:

Time Periods - Filter content from the last few hours to the past 30+ days
Order By - Sort candidates by popularity, trending signals, chronological order, or random

Source-Specific Filters:

Zora Market Info - For Zora coins, filter by trading volume, price, market cap, and holder count
App FIDs - Filter Farcaster posts by the app they were created in

These filters work together to create highly targeted candidate pools. You can combine multiple filters to build feeds that match your exact content requirements—from "tech news from verified accounts in the last 7 days" to "viral gaming content with high engagement."

Diversity Controls

Prevent feed monotony and ensure content variety with built-in diversity controls. Set limits on how many posts can appear from a single author and enforce minimum spacing between posts from the same creator. This ensures your users see a diverse range of voices and perspectives, not just the same few creators dominating their feed.

Fallbacks and Cold Start

Ensure your feed never runs dry with intelligent feed composition. Configure up to 3 fallback feeds that activate automatically when your primary feed runs out of content. Set up cold start strategies for new users who lack interaction history. This guarantees a smooth user experience even when your primary filters are highly restrictive or when serving users with limited engagement data.

How the Feed Builder Works

The Simplified Process

Choose a Template - Start with a pre-configured template on your Dashboard or create from scratch
Configure Your Feed - Use the visual interface to set:
- Content filters (topics, authors, channels, time periods, etc.)
- Ranking algorithms (balanced, interest-based, affinity-based, trending, etc.)
- Visibility rules (social proof, interaction filters, etc.)
- Feed construction (fallbacks, cold starts, promotions)
Save and Get Your feed_id - Once saved, Feed Builder generates a unique feed_id
Use in Your API Calls - Include the feed_id in your Get Recommendations API requests

What You Get: The `feed_id`

The feed_id is a unique identifier (e.g., feed_390, feed_624) that represents your complete feed configuration. Think of it as a shortcut that encapsulates all your settings:

All filter configurations
Scoring algorithm selection
Visibility filter settings
Feed construction logic (fallbacks, cold starts, promotions)

When you include a feed_id in an API call, it behaves exactly as if you passed all those parameters directly to the API.

How It Works Under the Hood

When you save a feed configuration in Feed Builder, ❜embed stores a complete copy of all your settings associated with that feed_id. When an API call includes a feed_id, the system:

Retrieves the stored configuration for that feed_id
Applies all the filters, scoring, and construction logic you configured
Generates personalized recommendations based on your settings
Returns the ranked list of content items

The API call with a feed_id behaves identically to passing all those parameters directly—Feed Builder just makes it easier to manage and update.

Overriding `feed_id` Settings

You can think of feed_id as the best default base configuration. Any parameters you pass directly in the API call will override the values set in the feed_id configuration.

Example:

Your feed_id might be configured with top_k: 25, but for a specific API call, you want 50 items:

{
  "feed_id": "feed_390",
  "user_id": "16085",
  "top_k": 50 // This overrides the feed_id's default of 25
}

This flexibility allows you to:

Use feed_id for standard behavior
Override specific parameters when needed
Test different settings without modifying the feed_id configuration

Common Workflows

Creating Your First Feed

Log in to Feed Builder
Select a template (e.g., "For You" feed)
Customize filters for your use case
Save and get your feed_id
Integrate feed_id into your application
Monitor and iterate

Updating an Existing Feed

Open your feed_id in Feed Builder
Modify the configuration (filters, scoring, etc.)
Save changes
Changes are immediately live for all API calls using that feed_id

Add in a Promotion Feed

Create a new feed with your promotion filters
Configure promotion settings (feed blend or specific items)
Save to get a feed_id
Use in API calls

A/B Testing Two Feeds

Create two feed_ids with different configurations
Assign feed_id_1 to 50% of users, feed_id_2 to the other 50%
Monitor performance metrics
Keep the winning configuration

Integration Examples

Basic Integration

const response = await fetch("https://api.getembed.ai/casts/feed/for-you", {
  method: "POST",
  headers: {
    Authorization: "Bearer mbd-YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    feed_id: "feed_390",
    user_id: "16085",
    top_k: 25,
  }),
});

const feed = await response.json();

Using the ❜embed SDK

import { EmbedClient } from "@embed-ai/sdk";

const client = new EmbedClient({
  apiKey: "mbd-YOUR_API_KEY",
});

const feed = await client.byUserId({
  feedId: "feed_390",
  userId: "16085",
  topK: 25,
});

Overriding Feed Settings

// Use feed_id defaults but override top_k for this call
const feed = await client.byUserId({
  feedId: "feed_390",
  userId: "16085",
  topK: 50, // Overrides feed_id's default
  returnMetadata: true, // Overrides feed_id's default
});

Troubleshooting

Feed Not Returning Results

Check that your feed_id is correctly saved in Feed Builder
Verify your filters aren't too restrictive
Ensure you're passing a valid user_id or wallet_address
Check that your API key has access to the feed

Changes Not Reflecting

Confirm you saved the changes in Feed Builder
Verify you're using the correct feed_id in API calls
Check for any parameter overrides that might be conflicting

Feed Performance Issues

Review your filter configurations—too many filters can reduce candidate pool
Check your scoring algorithm selection
Consider using fallback feeds to ensure content availability
Monitor API response times and adjust top_k if needed

Next Steps

Explore the AI pipeline to understand what powers your feeds
Read Essentials - What Makes a Good Feed? for best practices
Check out the Get Recommendations API Documentation for API details
Try the ❜embed SDK for easier integration

Summary

The Feed Builder is your no-code solution for creating powerful, personalized content feeds. With a simple visual interface, you can configure complex feed logic and get a feed_id that unlocks seamless integration with the Get Recommendations API. Whether you're a developer looking to iterate quickly or a non-technical team member managing content, Feed Builder makes feed creation accessible to everyone.

Key Takeaways:

✅ No-code visual interface for feed configuration
✅ feed_id is the key to using the Get Recommendations API
✅ Instant updates without code deployments
✅ Easy A/B testing and experimentation
✅ Non-technical team members can manage feeds
✅ Override any feed_id setting in API calls

Start building your first feed in Feed Builder today!