Documentation
Everything you need to know to get the most out of Surfeed.
Getting Started
Surfeed is an AI-powered platform that discovers trending content in your niche, generates tweets in your unique voice, and publishes them on autopilot. Whether you want full manual control or a completely hands-off experience, Surfeed adapts to your workflow.
Getting Started with Surfeed
Coming soon
Quick Start Checklist
Create your account
Sign up with your email at surfeed.io.
Run the setup wizard
The wizard walks you through niche, goals, audience, and tone so the AI can match your voice from day one.
Connect your X account
Authorize Surfeed via OAuth so it can post on your behalf.
Create a feed
Pick a content source (GitHub, RSS, Reddit, Hacker News, or Product Hunt) and configure what to track.
Run the feed
Click “Run now” or wait for the automatic schedule. Surfeed fetches and scores fresh content.
Generate tweets
Select high-scoring content and generate tweet drafts. Each generation produces two variations to choose from.
Schedule your tweets
Drag tweets into schedule slots or let autopilot fill them for you.
Publish
The scheduler publishes tweets at their scheduled times. Sit back and watch your analytics grow.
Creating Your Account & Connecting X
Sign up with your email and then connect your X (Twitter) account via OAuth. Surfeed needs read and write access to post tweets on your behalf. You can switch between connected X accounts from the sidebar.
Your credentials are stored securely and you can revoke access at any time from your X settings or from the Accounts page in Surfeed.
The Setup Wizard
After connecting your X account, the setup wizard guides you through five steps so Surfeed's AI can generate tweets that sound like you from day one.
Setup Wizard Walkthrough
Coming soon
Account Info
Confirm your display name, X handle, and avatar.
Niche Selection
Tell Surfeed what topics you cover. This drives content discovery and scoring.
Goals & Audience
Define what you want to achieve on X and who your target audience is (e.g. “Senior developers interested in AI tools”).
Vibe & Tone
Choose from four tone presets — Casual Expert, Professional, Enthusiastic, or Witty — and optionally paste example tweets that represent your style.
AI Strategy Generation
Surfeed generates a personalized content strategy based on everything you provided. Review and tweak it, then you're ready to go.
Feeds & Content Discovery
Feeds are automated content scrapers that monitor sources across the web. Each feed runs on a schedule, fetching fresh content and feeding it into your tweet pipeline. Surfeed supports five built-in plugins:
- GitHub — Trending repos and search-based discovery
- RSS — Any RSS or Atom feed
- Reddit — Top posts from subreddits you choose
- Hacker News — Top, new, best, Ask HN, and Show HN stories
- Product Hunt — New product launches by category
Free plans have access to GitHub and RSS. Pro and Max plans unlock Reddit, Hacker News, and Product Hunt.
Creating and Configuring a Feed
Coming soon
GitHub Plugin
Discover trending repositories or search GitHub with advanced query syntax. Great for developer-focused accounts that want to share new open-source projects.
Basic Config
| Field | Type | Default | Description |
|---|---|---|---|
| Type | select | search | Search GitHub with a query or get trending repositories |
| Search Query | textarea | — | GitHub search syntax (e.g. "topic:ai stars:>100"). Required for search type. |
| Minimum Stars | number | 0 | Filter repositories by minimum star count |
| Languages | text | — | Comma-separated list of programming languages (e.g. typescript, python, rust) |
| Max Repositories | number | 30 | Maximum repositories per run (1–100) |
Advanced Config
| Field | Type | Default | Description |
|---|---|---|---|
| Created After | text | — | Only include repos created after this date (YYYY-MM-DD) |
RSS Plugin
Monitor any RSS or Atom feed. Use this for blogs, newsletters, news sites, or any source that publishes a feed.
Basic Config
| Field | Type | Default | Description |
|---|---|---|---|
| Feed URL | text (required) | — | The URL of the RSS/Atom feed to monitor |
| Max Items | number | 10 | Maximum items per run (1–100) |
Advanced Config
| Field | Type | Default | Description |
|---|---|---|---|
| Include Content | boolean | false | Fetch full article content (if available in feed) |
| Keyword Filter | text | — | Only include items containing these keywords (comma-separated) |
| Exclude Keywords | text | — | Exclude items containing these keywords (comma-separated) |
/feed, /rss, or /feed.xml.Reddit Plugin
Track top posts from subreddits relevant to your niche. Filter by sort order, time range, and minimum upvotes to surface only high-quality discussions.
Basic Config
| Field | Type | Default | Description |
|---|---|---|---|
| Subreddits | text (required) | — | Comma-separated list of subreddits (without r/) |
| Sort | select | hot | Sort order: hot, top, rising, or new |
| Time Range | select | day | Time range for "top" sort: hour, day, week, month, year, all |
| Min Upvotes | number | 50 | Only include posts with at least this many upvotes |
Advanced Config
| Field | Type | Default | Description |
|---|---|---|---|
| Max Items | number | 25 | Max items per subreddit (1–100) |
| Keyword Filter | text | — | Only include posts containing these keywords (comma-separated) |
| Exclude Keywords | text | — | Exclude posts containing these keywords (comma-separated) |
| Links Only | boolean | false | Only collect posts that link to external content (skip self posts) |
Hacker News Plugin
Pull stories from Hacker News sections. Ideal for tech and startup-focused accounts.
Basic Config
| Field | Type | Default | Description |
|---|---|---|---|
| Section | select | top | HN section: top, new, best, ask, or show |
| Min Score | number | 50 | Only include stories with at least this many upvotes |
| Max Items | number | 25 | Maximum stories to collect (1–100) |
Advanced Config
| Field | Type | Default | Description |
|---|---|---|---|
| Keyword Filter | text | — | Only include stories containing these keywords (comma-separated) |
| Exclude Keywords | text | — | Exclude stories containing these keywords (comma-separated) |
| Links Only | boolean | false | Only collect stories that link to external content (skip Ask HN / text posts) |
Product Hunt Plugin
Track new product launches on Product Hunt by category. Perfect for accounts that cover startups, SaaS, or new tools.
Basic Config
| Field | Type | Default | Description |
|---|---|---|---|
| Categories | multiselect (required) | — | Categories to monitor: AI, Productivity, Developer Tools, Design Tools, Marketing, Finance, Education, Health & Fitness, Social Media, E-Commerce, Analytics, Nocode, SaaS, Open Source |
| Max Items | number | 25 | Maximum products to collect (1–50) |
| Keyword Filter | text | — | Only include products matching these keywords (comma-separated) |
Advanced Config
| Field | Type | Default | Description |
|---|---|---|---|
| Exclude Keywords | text | — | Exclude products containing these keywords (comma-separated) |
How Content Scoring Works
Every piece of discovered content receives an AI-generated relevance score from 0–10. A single AI call batch-scores all items from a feed run.
Scoring Criteria
- Relevance to your target audience
- Tweet-worthiness — would this make a compelling tweet?
- Quality and uniqueness of the content
- Alignment with preferred categories (boost) vs excluded categories (penalty)
Items scoring 5.0 or above are eligible for autopilot tweet generation. You can adjust the minimum quality score threshold in your account settings (the Quality Score setting, default 7.0) to control how selective autopilot is.
How AI Generates Tweets
When you generate a tweet from a piece of content, Surfeed's AI creates two variations — giving you options to pick from or edit. Each variation is capped at 280 characters (X's hard limit).
The AI considers your brand voice, tone, target audience, custom prompt instructions, and example tweets when crafting each variation. For content items, the source URL is automatically included in the tweet.
You can regenerate any tweet to get a completely new version, edit it manually, or approve it as-is. In autopilot mode, only the “standard” variation is kept to avoid duplicate tweets about the same content.
Generating and Editing Tweets
Coming soon
Brand Voice & Tone Settings
Your brand voice configuration tells the AI how to write. Choose from four tone presets:
Casual Expert
Friendly but knowledgeable
Professional
Formal and business-like
Enthusiastic
Excited and energetic
Witty
Clever and humorous
Beyond tone, you can configure:
- Brand voice guidelines — Free-text description of how this account should sound
- Example tweets — Paste real tweets that represent your style (3–5 recommended)
- Custom prompt instructions — Additional instructions appended directly to the AI prompt
- Emoji & hashtag preferences — Toggle emojis (max count) and hashtags on or off
- Tweet language — Generate tweets in English, French, Spanish, German, Portuguese, Italian, Japanese, Chinese, Korean, Arabic, or Dutch
Settings That Matter
If your generated tweets feel generic, these are the settings to tune — in order. Open Settings and work through them top to bottom.
Write custom prompt instructions
This is the single most effective way to control the AI. Add specific rules about what to do and what to avoid.
Add 3–5 example tweets
Paste real tweets that represent how you want to sound. The AI mimics their style, length, and structure. Pick your highest-engagement tweets and mix formats — short takes, link shares, and opinions.
Describe your brand voice
Write a short description of how this account should sound. Be specific — vague descriptions produce vague tweets.
Define your target audience
This changes the AI's vocabulary and framing. “Senior developers building AI tools” produces very different tweets than “CS students learning to code”. Be as specific as you can.
Adjust the quality score threshold
The default is 7.0 on a 0–10 scale. If autopilot isn't generating enough tweets, try lowering it to 6.0. If you're getting low-quality content, raise it to 8.0.
Set preferred & excluded categories
Content matching your preferred categories scores higher; excluded categories score lower. This filters what reaches tweet generation — set them so only on-brand content gets through.
Setting Up Your Schedule
The Schedule page lets you define time slots for when tweets should be published. You can set different slots for different days of the week, targeting the times when your audience is most active.
The scheduler checks every minute for tweets whose scheduled time has arrived and posts them automatically. If a slot has no tweet assigned, it's simply skipped.
Setting Up Your Schedule
Coming soon
Key scheduling settings on your account:
- Max Posts Per Day — Maximum tweets per day (default: 3)
- Min Hours Between Posts — Minimum hours between posts (default: 4)
- Preferred Posting Times — Your preferred time slots (e.g. 09:00, 14:00, 19:00). Autopilot uses these when scheduling tweets.
Autopilot Deep Dive
Surfeed offers three operating modes for each account:
- Manual — Content is discovered and scored, but you generate and approve every tweet yourself.
- Smart Drafts — AI automatically generates tweet drafts from top-scoring content and saves them as drafts for your review before publishing.
- Full Autopilot — AI generates tweets and schedules them at your preferred posting times automatically. Fully hands-off.
Autopilot in Action
Coming soon
How the Autopilot Pipeline Works
Feed runs
Your feed fetches fresh content from its configured source.
AI batch scoring
All new items are scored 0–10 in a single AI call based on your audience, brand voice, and category preferences.
Top-N selection
Items scoring 5.0 or above are eligible. The actual count is capped by your remaining daily post capacity and monthly AI generation quota.
Analysis (repos only)
GitHub repositories are analyzed for a short AI summary before tweet generation.
Tweet generation
One tweet is generated per selected item (the standard variation only, to avoid duplicates).
Save or schedule
Smart Drafts: Tweets are saved as drafts for your review. Full Autopilot: Tweets are scheduled at your preferred posting times, respecting the minimum hours between posts.
Scheduler posts
The scheduler runs every minute and publishes tweets whose scheduled time has arrived.
Analytics
The Dashboard gives you an at-a-glance overview of your account performance: tweets posted, content discovered, schedule utilization, and autopilot status. Use it to monitor how Surfeed is performing and identify areas for optimization.
The Analytics page goes deeper with charts showing posting frequency, engagement trends, and content source performance over time. Key metrics tracked:
- Impressions, engagements, and engagement rate per tweet
- Likes, retweets, replies, and bookmarks
- URL clicks and profile clicks
- Performance by content source (which feeds drive the best tweets)
- Posting frequency and schedule adherence
Free plans get basic analytics with 30-day retention. Pro and Max plans get full analytics with unlimited retention. Max plans can also export analytics data and access AI-powered insights.
CSV Import
Import your X Analytics data to help Surfeed understand what content performs best for your audience. Available on Pro and Max plans.
How to Export from X Analytics
Go to analytics.x.com
Click "Export data" in the top-right
Select your date range and download the CSV
Upload the CSV in Surfeed under Settings → Analytics Import
Supported Columns
Surfeed recognizes these column headers (case-insensitive):
Managing Multiple X Accounts
Surfeed supports managing multiple X accounts from a single login. Each account has its own feeds, brand voice, schedule, and autopilot settings. Switch between accounts using the account switcher in the sidebar.
The number of accounts you can connect depends on your plan:
- Free — 1 account
- Pro — 1 account
- Max — 3 accounts
Best Practices & Tips
Writing Good Example Tweets
- Add 3–5 examples — enough for the AI to learn your style, but not so many it gets confused.
- Use diverse formats — mix short punchy takes, longer insight threads, and link-sharing tweets.
- Pick high-engagement tweets — your best-performing tweets teach the AI what works for your audience.
Feed Configuration Combos
- Developer audience: GitHub (trending + TypeScript/Rust) + Hacker News (Show HN) + RSS (your favorite tech blogs)
- Startup audience: Product Hunt (AI + SaaS) + Reddit (r/startup, r/SaaS) + Hacker News (top)
- Design audience: Product Hunt (Design Tools) + Reddit (r/design, r/UXDesign) + RSS (design blogs)
X Algorithm Tips
Ranked by impact on reach:
Tier 1 — Strongest Signals
- Copy-link shares are the #1 ranking factor. Write tweets people want to save and share privately.
- DM shares signal extremely high value to the algorithm.
- Quote tweets outweigh plain retweets. Write tweets that provoke people to add their own take.
- First 2 hours are critical. Out-of-network discovery requires high engagement early. Post when your audience is active.
Tier 2 — Important Signals
- First line is everything — lead with a bold claim, stat, or question to stop the scroll.
- Questions drive replies — replies are a strong engagement signal.
- Threads increase dwell time — multi-tweet threads keep readers engaged longer.
Tier 3 — Minor Signals
- Emojis — can increase engagement but overuse looks spammy.
- Hashtags — 1–2 relevant hashtags help discovery; more than that hurts reach.
Posting Frequency
- Aim for 2–4 tweets per day.
- Space them 4+ hours apart to avoid the author diversity penalty.
- Quality over quantity — fewer, high-quality posts outperform a high volume of mediocre content.
Plans & Quotas
Surfeed offers three plans. All limits reset monthly. See the Pricing page for current prices.
| Feature | Free | Pro | Max |
|---|---|---|---|
| X Accounts | 1 | 1 | 3 |
| Feeds | 1 | 5 | Unlimited |
| AI Generations / month | 10 | 200 | 500 |
| Published Posts / month | 5 | 200 | 500 |
| Content Sources | GitHub, RSS | All 5 | All 5 |
| Autopilot | — | ✓ | ✓ |
| Analytics | Basic (30 days) | Full | Full |
| Analytics Export | — | — | ✓ |
| AI Insights | — | — | ✓ |
| Strategy Generation | — | ✓ (1 regen/mo) | ✓ (1 regen/mo) |
| CSV Import | — | ✓ | ✓ |
Troubleshooting
My X token expired. What do I do?
Go to Settings → Accounts and click “Reconnect”. You'll re-authorize via OAuth. All your drafts, schedule, and settings are preserved.
My feed runs are failing.
Check the feed's run history for error messages. Common causes: invalid RSS URL, GitHub rate limiting (try reducing Max Repositories), or subreddit names with typos. If the source is temporarily down, the next scheduled run will retry automatically.
Autopilot isn't generating any tweets.
Check these in order:
- Make sure your account is on a Pro or Max plan.
- Verify autopilot mode is set to Smart Drafts or Full Autopilot, not Manual.
- Check that your feed actually found new items in its last run.
- If items were found but no tweets were generated, their scores may be below 5.0 — try broadening your feed's configuration or adjusting your category preferences.
My tweets aren't being published.
Check that:
- You have schedule slots configured.
- Tweets are in “scheduled” status (not just “draft”).
- Your X account connection is active.
- You haven't exceeded your monthly published posts quota.
I hit my monthly quota. What happens?
When you exceed your AI generation or published post limit, those features stop until next month. Your existing scheduled tweets will still post, and feeds will still collect content. Upgrade your plan for higher limits.
The generated tweets don't match my voice.
The most impactful fix is adding custom prompt instructions with specific rules and 3–5 example tweets. See the section for the full priority list.
Can I edit tweets after they're generated?
Yes. You can edit any draft tweet before approving it. You can also regenerate a tweet to get a completely new version based on the same source content.
Is there a limit on how many tweets Surfeed can generate?
Yes. Free: 10 AI generations/month, Pro: 200/month, Max: 500/month. Each tweet generation counts as one generation. Check the Pricing page for current details.