Contrails

Contrails is a developer-friendly feature from Graze.social, designed to provide real-time post streams from the Bluesky network, filtered through any custom Graze feed. It acts as a drop-in replacement for the official Jetstream firehose, dramatically reducing unnecessary bandwidth by streaming only the posts that match a given feed’s algorithm. Contrails is here to help you build smarter, leaner, real-time Bluesky apps. Happy streaming!

🌤️ What is Contrails?

Contrails is a WebSocket-based endpoint that mirrors the Bluesky Jetstream format, but instead of providing every single post on the network, it filters them down to the posts that would appear in a specific Graze feed. This provides developers with:

• Efficient streaming: Only get posts relevant to your feed algorithm.
• Jetstream compatibility: Same event structure and schema.
• Easy integration: Use your existing feed or create a new one via Graze.social.
• Save bandwidth: Great for developers building lightweight services, apps, bots, and analytics dashboards.

🛠 Usage

To start using Contrails:

1. Build a feed using the no-code feed editor at graze.social.
2. Turn on Contrails in your feed's settings.
3. Identify the feed URI, which can be either:
   1. A public-facing Bluesky feed URL (e.g., https://bsky.app/profile/example.com/feed/news)
   2. An AT-URI (e.g., at://example.com/app.bsky.feed.generator/news)
4. Connect to the WebSocket: wss://api.graze.social/app/contrail?feed={FEED_URI}

You’ll begin receiving a Jetstream-style stream of JSON updates that match your feed logic.

🔄 Example with websocat

Connect to a Graze feed via CLI:

websocat "wss://api.graze.social/app/contrail?feed=at://example.com/app.bsky.feed.generator/news"

This will stream only the posts that would appear on the selected Graze feed.

📦 Ideal Use Cases

• Live-updating dashboards for community-focused feeds.
• Bot accounts that need to react only to posts from a specific subnetwork.
• Analytics tooling or moderation systems watching a narrow slice of content.

✨ Under the Hood

Contrails wraps Jetstream semantics in a filtering layer powered by Graze’s feed system. Every message you receive has already passed through your algorithm’s logic, so what you see is what you get.

Behind the scenes:

• Graze executes your feed logic in real-time.
• Contrails subscribes to post events across the network.
• Only posts passing your algorithm are delivered.

🙋‍♀️ Feedback & Contributions

Contrails is an early developer-focused feature. If you find issues or have feature requests, contact the Graze team via @graze.social on Bluesky.