Step 1: Candidate Generation

Define the pool of content your feed will draw from. This step sets the foundation for your feed by selecting which content gets considered. Filters narrow down the entire universe of recommendable content to exclude content with certain attributes, making content more relevant to your users and the nature of your application.

Time Period Filters

Control the time window for candidate generation.

`start_timestamp`

Return only posts created after this timestamp.

Format Options:

Epoch timestamp (Unix timestamp): "1577836800"
Relative time syntax: "days_ago:7" or "hours_ago:12"

Example:

{
  "filters": {
    "start_timestamp": "days_ago:7"
  }
}

Use Cases:

Show only recent content (last 7 days)
Filter content by specific date ranges
Ensure feed freshness

`end_timestamp`

Return only posts created before this timestamp.

Format Options:

Epoch timestamp: "1704153600"
Relative time syntax: "days_ago:1" or "hours_ago:6"

Example:

{
  "filters": {
    "end_timestamp": "1704153600"
  }
}

Use Cases:

Historical content feeds
Time-bounded content discovery
Event-specific feeds

Source Filters

`app_fids`

Filter content by the source app or client that created it.

Description: Return only posts that were created from these source apps (specified as the app's signer FID).

Example:

{
  "filters": {
    "app_fids": ["9152", "6131", "193137"]
  }
}

Use Cases:

Create feeds specific to certain apps (e.g., Warpcast, Farcaster clients)
Filter by client type or version
Curate content from trusted sources

Geographic Filters

`geo_locations`

Filter content by geographic location where it was created.

Description: Return only posts that were created from these geo-locations, specified as strings of latitude,longitude pairs (to 2 decimal places, as specified in Farcaster).

Format: "latitude,longitude" (e.g., "48.86,2.35")

Example:

{
  "filters": {
    "geo_locations": ["48.86,2.35", "51.51,-0.13", "34.05,-118.24"]
  }
}

Use Cases:

Location-based feeds (e.g., "New York" feed)
Regional content discovery
Event-specific location feeds

`remove_geo_locations`

Exclude posts from specific geographic locations.

Note: This is ignored if geo_locations is defined.

Example:

{
  "filters": {
    "remove_geo_locations": ["48.86,2.35"]
  }
}

Author Filters

`author_ids`

Specify which authors' content to include in the feed.

Three Modes:

Specific Author IDs: List of FIDs

{
  "filters": {
    "author_ids": ["1423", "513", "99"]
  }
}

Following: Use "following" to include only content from users followed by the current user_id
```
{
  "filters": {
    "author_ids": ["following"]
  }
}
```
Specific User's Following: Include content from users followed by a specific user
```
{
  "filters": {
    "author_ids": ["following:6473"]
  }
}
```

Use Cases:

Creator-focused feeds
Curated author lists
Following-based feeds
Influencer content feeds

`remove_author_ids`

Exclude posts from specific authors.

Note: This is ignored if author_ids is defined.

Example:

{
  "filters": {
    "remove_author_ids": ["1423", "513"]
  }
}

Channel Filters

`channels`

Filter content by channel membership.

Description: Return only posts that belong to these channels, specified by channel URLs (root_parent_url).

Example:

{
  "filters": {
    "channels": [
      "https://farcaster.group/founders",
      "https://warpcast.com/~/channel/reneecampbell",
      "https://warpcast.com/~/channel/fumblingdaily"
    ]
  }
}

Use Cases:

Topic-specific feeds (e.g., "Founders" channel)
Community-based content
Curated channel feeds

`remove_channels`

Exclude posts from specific channels.

Example:

{
  "filters": {
    "remove_channels": ["https://farcaster.group/founders"]
  }
}

AI Label Filters

`ai_labels`

Filter content by AI-detected labels and categories.

Description: Return only posts that have these AI labels. Labels are organized into categories:

Topic Labels:

arts_culture, business_entrepreneurs, celebrity_pop_culture, diaries_daily_life, family, fashion_style, film_tv_video, fitness_health, food_dining, gaming, learning_educational, music, news_social_concern, other_hobbies, relationships, science_technology, sports, travel_adventure, youth_student_life

Sentiment Labels:

positive, neutral, negative

Emotion Labels:

anger, anticipation, disgust, fear, joy, love, optimism, pessimism, sadness, surprise, trust

Moderation Labels:

llm_generated, spam, sexual, hate, violence, harassment, self_harm, sexual_minors, hate_threatening, violence_graphic

Web3 Topic Labels:

web3_nft, web3_defi, web3_infra, web3_industry, web3_consumer

Example:

{
  "filters": {
    "ai_labels": ["business_entrepreneurs", "science_technology", "positive"]
  }
}

Use Cases:

Topic-specific feeds (e.g., tech, sports, music)
Sentiment-based filtering
Content moderation
Web3-focused feeds

Note: You can optionally specify threshold scores for each label to fine-tune behavior. The system default threshold will be used if not specified.

`dynamic_ai_labels`

Use AI to dynamically determine appropriate labels based on user behavior.

Description: Include posts that match the dynamically determined AI labels for the specified user. The system will decide appropriate labels based on the user's context and behavior.

Example:

{
  "filters": {
    "dynamic_ai_labels": {
      "user_id": "current user_id"
    }
  }
}

Use Cases:

Personalized topic discovery
Adaptive content filtering
User behavior-based labeling

`remove_ai_labels`

Exclude posts with specific AI labels.

Example:

{
  "filters": {
    "remove_ai_labels": ["spam", "hate", "violence"]
  }
}

`remove_dynamic_ai_labels`

Remove posts that match dynamically determined AI labels for a specific user.

Example:

{
  "filters": {
    "remove_dynamic_ai_labels": {
      "user_id": "6473"
    }
  }
}

Embed Domain Filters

`embed_domains`

Filter content by embedded domains.

Description: Return only posts with specific domains embedded.

Example:

{
  "filters": {
    "embed_domains": [
      "paragraph.xyz",
      "mirror.xyz",
      "mint.fun",
      "zora.co",
      "drakula.app"
    ]
  }
}

Use Cases:

NFT-focused feeds (mint.fun, zora.co)
Video feeds (drakula.app)
Article feeds (paragraph.xyz, mirror.xyz)
Platform-specific content

Publication Type Filters

`publication_types`

Filter content by publication type.

Available Types:

image - Image posts
audio - Audio posts
video - Video posts (with optional video-specific filters)

Simple Format:

{
  "filters": {
    "publication_types": ["image", "audio", "video"]
  }
}

Video with Additional Filters:

{
  "filters": {
    "publication_types": [
      "image",
      {
        "type": "video",
        "video_duration": {
          "min": 1.5,
          "max": 10.0
        },
        "video_orientation": "wide",
        "video_languages": ["en", "es"]
      }
    ]
  }
}

Video-Specific Options:

video_duration: Filter by duration in minutes (min/max)
video_orientation: wide, classic, square, vertical, tall, portrait
video_languages: Array of language codes

Use Cases:

Video-only feeds
Image-focused feeds
Short-form video feeds (with duration filters)
Landscape video feeds

`remove_publication_types` (Zora only)

Exclude specific publication types (Zora feeds only).

Example:

{
  "filters": {
    "remove_publication_types": ["audio"]
  }
}

Language Filters

`languages`

Filter content by language.

Available Language Codes:

ar (Arabic), bn (Bengali), de (German), en (English), es (Spanish), fa (Persian), ga (Irish), he (Hebrew), hi (Hindi), id (Indonesian), it (Italian), ja (Japanese), mul (Multiple languages), pt (Portuguese), yo (Yoruba), zh (Chinese), xew (Enawene Nawe), zxx (No linguistic content)

Example:

{
  "filters": {
    "languages": ["en", "es"]
  }
}

Use Cases:

Localized feeds
Multi-language support
Language-specific content discovery

Engagement Filters

`engagement`

Filter posts by engagement metrics (likes, comments, shares).

Properties:

min_likes_count - Minimum number of likes
max_likes_count - Maximum number of likes
min_comments_count - Minimum number of comments
max_comments_count - Maximum number of comments
min_shares_count - Minimum number of shares
max_shares_count - Maximum number of shares

Example:

{
  "filters": {
    "engagement": {
      "min_likes_count": 10,
      "min_comments_count": 5,
      "max_likes_count": 100
    }
  }
}

Use Cases:

High-engagement feeds (minimum thresholds)
Emerging content (low maximum thresholds)
Quality control (minimum engagement requirements)

Content Filters

`keywords`

Filter posts by keyword content.

Description: Return only posts that contain these keywords. Keywords should be separated by commas.

Example:

{
  "filters": {
    "keywords": "crypto,AI,web3"
  }
}

Use Cases:

Topic-specific keyword feeds
Event-based content
Trend-based filtering

`remove_keywords`

Exclude posts containing specific keywords.

Example:

{
  "filters": {
    "remove_keywords": "spam,clickbait"
  }
}

`character_length`

Filter posts by text length.

Properties:

min - Minimum number of characters (minimum: 0)
max - Maximum number of characters (minimum: 0)

Example:

{
  "filters": {
    "character_length": {
      "min": 50,
      "max": 500
    }
  }
}

Use Cases:

Long-form content feeds
Short-form content feeds
Content length quality control

Ordering (Candidate Generation)

`order_by`

Control the initial ordering of candidates before ranking.

Available Options:

popular_v0.0.1 - Order by popularity metrics
trending_v0.0.1 - Order by trending signals
chronological - Order by creation time (newest first)
random - Random ordering

Example:

{
  "filters": {
    "order_by": "trending_v0.0.1"
  }
}

Use Cases:

Trending-first feeds
Chronological feeds
Randomized discovery

Note: This ordering is applied during candidate generation, before the ranking step.

Zora-Specific Filters

For Zora coin feeds, additional filters are available:

`market_info` (Zora only)

Filter Zora coins by market information metrics.

Properties:

total_volume - Filter by total trading volume (min/max in USDC)
volume_24h - Filter by 24-hour trading volume (min/max in USDC)
price_usdc - Filter by current price (min/max in USDC)
market_cap - Filter by market capitalization (min/max in USDC)
market_cap_delta_24h - Filter by 24-hour market cap change (min/max in USDC)
unique_holders - Filter by number of unique holders (min/max)

Example:

{
  "filters": {
    "market_info": {
      "total_volume": {
        "min": 10000.0,
        "max": 1000000.0
      },
      "price_usdc": {
        "min": 0.01,
        "max": 100.0
      }
    }
  }
}

`remove_market_info` (Zora only)

Exclude coins matching specific market information criteria.

`remove_time_period` (Zora only)

Exclude coins within a specific time period.

Time Period Filters

start_timestamp

end_timestamp

Source Filters

app_fids

Geographic Filters

geo_locations

remove_geo_locations

Author Filters

author_ids

remove_author_ids

Channel Filters

channels

remove_channels

AI Label Filters

ai_labels

dynamic_ai_labels

remove_ai_labels

remove_dynamic_ai_labels

Embed Domain Filters

embed_domains

Publication Type Filters

publication_types

remove_publication_types (Zora only)

Language Filters

languages

Engagement Filters

engagement

Content Filters

keywords

remove_keywords

character_length

Ordering (Candidate Generation)

order_by

Zora-Specific Filters

market_info (Zora only)

remove_market_info (Zora only)

remove_time_period (Zora only)

`start_timestamp`

`end_timestamp`

`app_fids`

`geo_locations`

`remove_geo_locations`

`author_ids`

`remove_author_ids`

`channels`

`remove_channels`

`ai_labels`

`dynamic_ai_labels`

`remove_ai_labels`

`remove_dynamic_ai_labels`

`embed_domains`

`publication_types`

`remove_publication_types` (Zora only)

`languages`

`engagement`

`keywords`

`remove_keywords`

`character_length`

`order_by`

`market_info` (Zora only)

`remove_market_info` (Zora only)

`remove_time_period` (Zora only)