Articles on: API

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:
  4. A public-facing Bluesky feed URL (e.g., https://bsky.app/profile/example.com/feed/news)
  5. An AT-URI (e.g., at://example.com/app.bsky.feed.generator/news)
  6. 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.

Updated on: 26/09/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!