Bubble Docs
  • Introduction
  • New? Start Here
  • What is Bubble?
  • The Glossary
  • User manual
    • Getting started
      • What is Bubble?
      • Building for...
        • Web
        • Native iOS and Android
          • Mobile app quick start guide
          • What is a native mobile app?
          • Native mobile vs. web development
          • Differences in native and web elements
          • Native mobile app terminology
      • Building your first app
        • Planning features
        • Database structure
        • Design and UX
        • eCommerce and payments
          • Shopping cart
          • Checkout page
          • One-time payments
          • Subscriptions
          • Marketplace
      • Creating and managing apps
      • The Bubble editor
        • Tabs and sections
          • Design tab
            • The element tree
            • The property editor
          • Workflow tab
          • Data tab
          • Styles tab
          • Plugins tab
          • Settings tab
            • Application settings
              • Custom headers/body
              • Visual settings
              • Social media sharing
              • Translating your app
              • Email settings
              • Collaboration
            • Custom domain and DNS
          • Logs tab
        • Tools
          • Key features
          • The search tool
          • The Issue Checker
          • The element tree
          • The element property editor
          • The debugger
          • Notes
        • Previewing your app
      • Transitioning to Bubble from...
        • JavaScript
        • HTML and CSS
        • SQL
    • Design
      • Elements
        • Web app
          • The page
          • Containers
            • Groups
            • Repeating groups
            • Table elements
            • Popups
            • Floating groups
            • Group focus
          • Visual elements
          • Input forms
            • Text and numbers
            • Dates and time
            • File uploads
            • Selection controls
        • iOS and Android app
          • The view
          • Containers
          • Visual elements
          • Input forms
          • Mobile reusable elements
        • The element hierarchy
          • The element tree
        • Reusable Elements
      • Styling
        • Color variables
        • Font variables
        • Styles
        • Custom Fonts
      • Responsive design
        • Building responsive pages
        • Legacy articles
          • The Basics (Legacy)
          • Building Responsive Pages (Legacy)
          • Migrating Legacy Pages
          • Tips When Designing (Legacy)
      • Templates
      • The Component Library
      • Importing from Figma
    • Data
      • The database
        • Data types and fields
        • Creating, saving and deleting data
        • Finding data
        • Displaying data
        • Protecting data with privacy rules
        • The database editor
        • Export/import data
          • Exporting data
          • Importing data (CSV)
        • Working with location data
        • Using Algolia
        • Database structure by app type
          • Marketplace Apps
          • Directory & Listings Apps
          • Social Network Apps
          • SaaS Apps
          • Project Management Apps
          • CRM Apps
          • Professional Services Apps
          • On-demand Apps
          • Documentation/ CMS Apps
          • Applicant Tracking System (ATS) Apps
          • Portfolio Apps
          • Gallery Apps
          • Online Store / Ecommerce Apps
          • Blog Apps
          • Messaging App
          • Dashboards
          • Building Block Apps
          • Bubble as a backend
      • Files
      • Images
      • Static data
        • App texts (translations)
        • Option sets
      • Temporary data
        • Custom states
        • URL parameters
      • User accounts
        • Authentication plugins
          • Facebook plugin
          • Fitbit plugin
          • Google plugin
          • Instagram plugin
          • LinkedIn plugin
          • Pinterest plugin
          • Slack plugin
          • Wistia plugin
          • YouTube plugin
        • Cookies set by Bubble
      • Time, dates and time zones
    • Logic
      • The frontend and backend
      • Workflows
        • Events
          • Frontend events
            • Recurring workflows
            • Custom events
          • Backend events
            • Database trigger events
        • Actions
        • API Workflows
      • Dynamic expressions
      • Conditions
      • Navigation
        • Single-page applications (SPA)
        • Multi-page applications
        • Page slugs
      • Device resources
        • Location services
        • Camera/photo library
    • Workload
      • Understanding workload
        • Activity types
        • The workload calculation
        • Client-side and server-side processing
      • Tracking workload
        • Measuring
          • Using App Metrics
        • Monitoring
          • Workload notifications
          • Infinite recursion protection
      • Optimizing workload
        • Optimization framework
        • Optimization checklist
          • Page load
          • Searches
          • Workflows and actions
          • Backend workflows
        • Agency showcases
          • Minimum Studio
          • Neam
          • Support Dept
    • Security
      • Bubble's security features
      • Planning app security
      • Client-side and server-side
      • Bubble account security
      • App security
      • Page security
      • Database security
      • API security
        • API Connector security
        • Data API security
        • Workflow API security
      • Flusk
        • Overview
        • Flusk plan features
        • Getting started with Flusk
        • Flusk security tools
          • The Issues Explorer
          • Issue details
          • Tools and settings
            • Pages rating
            • Database rating
        • Flusk FAQ
      • Cookies
      • Security checklist
    • Previewing your app
      • Previewing a web app
      • Previewing a mobile app
    • Publishing your app
      • Web app
      • Native mobile app
        • Global native mobile settings
        • iOS App Store
        • Google Play Store
        • Publishing FAQ
    • AI
      • Generate apps with AI
        • About AI app generation
      • AI page designer
      • Connect to AI agents
    • Maintenance
      • Collaborators
      • Version control
        • Best practices: Version control
        • Transitioning from the legacy version control
        • Terminology: Version control
        • Version Control (legacy)
      • Commenting
      • Database maintenance
        • Copying the database
        • Restoring database backups
        • Bulk operations
          • Bulk operation methods compared
        • Wiping change history
      • Performance
        • Hard limits
        • Capacity Usage (legacy)
        • Notes on queries
      • SEO
        • Introduction to SEO
        • SEO: App
        • SEO: Page
      • Testing and debugging
        • Introduction to testing and debugging
        • The debugger
        • The server logs
        • Supported browsers
      • API workflow scheduler
    • Integrations
      • API
        • Introduction to APIs
          • What is a RESTful API?
        • The Bubble API
          • Bubble API terminology
          • Authentication
            • How to authenticate
            • No authentication
            • As a User
            • As an admin
          • The Data API
            • Data API Privacy Rules
            • Data API endpoints
            • Data API requests
          • The Workflow API
            • Workflow API privacy rules
            • Workflow API endpoints
            • API workflows
              • Creating API workflows
              • Scheduling API workflows
              • Recursive API workflows
              • API Workflow Scheduler
              • Case: Stripe notifications
        • The API Connector
          • Authentication
          • API Connector security
          • API guides
            • OpenAI
              • Authentication
              • Calls
                • ChatGPT
                  • Chat
            • Google Translate
              • How to setup Google API keys
          • Streaming API
        • API security
        • Plugins that connect to APIs
        • API Glossary
      • Plugins
        • What Plugins Can Do
        • Installing and using Plugins
        • Authentication plugins
        • Special Plugins
      • SQL Database Connector
      • Bubble App Connector
      • WorkOS
        • WorkOS SSO
        • WorkOS API
    • Infrastructure
      • Sub-apps
      • Bubble release tiers
      • Hosting and scaling
        • How Bubble hosting works
        • Scaling with Bubble
        • CDN (Cloudflare)
        • Bubble app names
        • Domain and DNS
      • Compliance
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks and standards
    • Bubble for Enterprise
      • Hosting and infrastructure
        • Dedicated instance
          • The Dedicated editor experience
          • Technical specs
          • Main cluster dependencies
          • Customizable options
          • Migration process
            • Pre-migration
            • During migration
            • Post-migration
      • Security and compliance
        • Single sign-on (SSO)
        • GDPR
        • SOC 2 Type II
        • HIPAA
        • Other frameworks
        • Bubble's security features
      • Admin and collaboration
      • Priority support
      • Billing and Payment Guideline for Dedicated Instances
  • Core Reference
    • Using the core reference
    • Bubble's Interface
      • Design tab
      • Design tab (Legacy)
      • Workflow tab
      • Data tab
      • Styles tab
      • Styles tab (Legacy)
      • Plugins tab
      • Settings tab
      • Logs tab
      • Template tab
      • Toolbar
      • Top and context menu options
      • Deployment and version control
        • Deployment & Version Control Dropdown (legacy)
      • Notes
    • Elements
      • Native mobile elements
        • View element
        • List component
      • General properties
      • General properties (Legacy)
      • Styling properties
      • Styling Properties (Legacy)
      • Responsive Properties
      • Responsive Properties (Legacy)
      • Conditional formatting
      • States
      • Page Element
        • Page Element (Legacy)
      • Visual Elements
      • Containers
      • Container Layout Types
      • Containers (Legacy)
      • Input Forms
      • Reusable Elements
      • Element Templates (legacy)
    • Workflows
    • Events
      • General events
      • Element events
      • Custom events
      • Recurring event
      • Database trigger event
    • Actions
      • Account
      • Navigation
      • Data (things)
      • Email
      • Element
      • Custom
    • On-device resources
    • Data
      • Data Sources
      • Operators and comparisons
      • Search
      • Privacy
    • Styles
    • API
      • The Bubble API
        • The Data API
          • Authentication
          • Data API endpoints
          • Data API requests
        • The Workflow API
      • The API Connector
        • Authentication
        • Adding calls
    • Bubble-made Plugins
      • AddtoAny Share Buttons
      • Airtable
      • API Connector
      • Blockspring
      • Box
      • Braintree
      • Bubble App Connector
      • Chart.js
      • Circle Music Player
      • Draggable Elements
      • Dropzone
      • Facebook
      • Fitbit
      • Full Calendar
      • Google
      • Google Analytics
      • Google Optimize
      • Google Places
      • Ionic Elements
      • iTunes
      • Slidebar Menu
      • LinkedIn
      • Localize Translation
      • Mixpanel
      • Mouse & Keyboard Interactions
      • Multiselect Dropdown
      • Progress Bar
      • Rich Text Editor
      • Rich Text Editor (Legacy)
      • Screenshotlayer
      • SelectPDF
      • Slack
      • Segment
      • Slick Slideshow
      • SQL Database Connector
      • Star Rating
      • Stripe
      • Tinder-like Element
      • Twitter
      • YouTube
      • Zapier
    • Application Settings
      • App plan
      • General
      • Domain / email
      • Languages
      • SEO / metatags
      • API
      • Collaboration
      • Sub-apps
      • Versions
  • Account & Marketplace
    • Account and billing
      • Pricing and plans
        • Plans and billing
        • Billing cycle
        • FAQ: Pricing and Workload
      • Account Management
      • Building Apps for Others
      • Selling on the Marketplace
      • Plans & Billing (legacy)
    • Official Bubble Certification
      • Hiring certified developers
    • Building Plugins
      • The Plugin Editor
      • General Settings
      • Updating to Plugin API v4
      • Adding API Connections
      • Building Elements
      • Building Actions
      • Loading Data
      • Publishing and versioning
      • Github Integration
    • Building Templates
    • Application and data ownership
    • Marketplace policies
    • Bug reports
  • Vulnerability Disclosure Policy
  • Beta features
    • About the Beta features section
    • Native mobile apps
Powered by GitBook
On this page
  • What is a streaming API?
  • What does selecting stream mean in an API call?
  • What is a streaming API used for
  • Setting up a streaming API
  • Enabling a streaming API response
  • Setting response fields
  • Using streaming APIs in workflows
  • Streaming API data sources

Was this helpful?

  1. User manual
  2. Integrations
  3. API
  4. The API Connector

Streaming API

Last updated 25 days ago

Was this helpful?

What is a streaming API?

Streaming API is a method of transmitting data from a server to a client in real time, as the data becomes available, rather than waiting for the entire response to be prepared before sending it all at once. This approach contrasts with traditional request-response APIs, where the client sends a request and waits for the full response to be delivered in a single package.

With streaming, data is sent in small chunks (called data frames) over a persistent connection. This allows the client to start processing information immediately, improving perceived speed and responsiveness

What does selecting stream mean in an API call?

When you select Stream from the list of data types in the API Connector in Bubble, you're telling Bubble how to handle the response it gets back from the API.

From a technical perspective, you're not choosing a different protocol (it’s still typically HTTPS), but you're defining how Bubble should handle the response.

  • Most APIs return a complete response all at once—typically in formats like JSON or XML. There's a request, and then a single response that ends the connection.

  • A streaming API works differently. It sends back a single response that remains open, allowing the server to deliver data gradually in chunks as it becomes available. Once all data has been sent, the server closes the connection to signal completion.

What is a streaming API used for

Streaming APIs are used in scenarios where it's useful or necessary to keep a connection open and receive data gradually over time, rather than all at once. For Bubble developers, one of the most common use cases involves integrating with large language models (LLMs) like OpenAI's ChatGPT.

With a traditional API response—such as one using JSON—the entire response is generated on the server and then sent to the client in a single package. This means the user doesn't see anything until the full message is ready, which can result in noticeable delays for complex or long responses.

Streaming changes that behavior. When streaming is enabled, the server starts sending parts of the response as soon as they’re ready. For example, with tools like ChatGPT or Claude, you might see the reply appear word by word or sentence by sentence, allowing users to follow along in real time as the model generates its output.

This approach improves perceived responsiveness and creates a more interactive user experience. While LLMs are a common use case today, streaming APIs are also widely used in other areas—such as financial market tickers, real-time analytics dashboards, and messaging bots—where timely, incremental data updates are essential.

Setting up a streaming API

Before setting up a streaming API, make sure of the following:

  • Ensure that the API service you are connecting to (such as ChatGPT) supports a streaming API response

  • Install the API Connector plugin

  • Set up the relevant API authentication for the service you want to connect to

  • Add your first API call

Enabling a streaming API response

To instruct Bubble that the streaming API response will be streamed, set the data type to Stream:

It’s important to note that many API services require an explicit instruction to enable streaming. For example, OpenAI’s ChatGPT API will return a regular JSON response by default unless you include a specific parameter (such as "stream": true) in your request.

This means that for streaming to work correctly, both sides need to be configured appropriately: your Bubble app must be set up to handle a stream, and the external service must be told to send the streaming API response. If either side is not properly configured, the streaming API initialization process may fail.

In the example below, we’re sending a few parameters to ChatGPT to instruct it to return a streaming API response in the right way:

This specifies which version of the language model you want to use (e.g. gpt-4, gpt-3.5-turbo).

This is the core of the request and represents the conversation history. It’s formatted as a list of message objects, where each object has two required fields:

Example:

{
  "messages": [
    { "role": "user", "content": "Please write me a medium-length poem." }
  ]
}

This field tells the model what the user has said and, optionally, includes prior conversation history for context.

This boolean parameter enables streaming if set to true. When streaming is enabled:

  • The response is returned as a series of partial chunks, rather than one complete response.

  • This allows your app to display content in real time as the model generates it, improving perceived performance and user experience.

If stream is set to false or omitted, the model responds in a traditional, full-response format (JSON).

This is an optional object that lets you modify the behavior of streaming API responses.

Currently, one available option is:

  • include_usage (boolean): If set to true, the final chunk in the stream will include token usage information, such as how many input and output tokens were consumed. This is useful for logging, usage tracking, or billing logic.

Example

{
  "stream_options": {
    "include_usage": true
  }
}

Note: This parameter only applies when stream: true is set.

Setting response fields

When you initialize an API call that returns a streaming API response, you'll receive a series of events known as chunks. Each chunk contains one or more fields, with each field representing a key-value pair of data returned from the stream.

To use this data effectively, you need to define how your app should handle each of these fields.

Setting up streaming API response fields

When initializing a streaming API call, the full response must be received before the initialization process can complete. As a result, initialization may take longer than with a standard (non-streaming) API call.

After initializing the call, the first step is to create a unique response field for every field you want to reference in your app. This allows you to access and work with the incoming data as it arrives in real time. Let’s continue the scenario of working with ChatGPT, and assume that you want to reference the following data:

  • Text stream - the incremental content generated by the model. When using streaming, this field updates continuously as each new token or word is returned by the model in real time.

  • Input tokens - the number of tokens used in the request payload.

  • Output tokens - The number of tokens generated in the response. This includes all tokens streamed or returned in the final output and helps you understand usage and billing impact.

To create new response field, follow these steps:

  1. Initialize the call and wait for the Returned values popup to appear

  2. Scroll down to Response fields

  3. Click Add new field +

  4. Give the response field a name, and select a data type

Response fields support the following types:

Field name
Description
Streamed

Text stream

Incremental text content (e.g. the content being streamed)

Yes

Text

A regular text value

No

Number

A regular numerical value

No

Yes/no

A true/false value

No

Using streaming APIs in workflows

Just like regular JSON API calls, streaming APIs can be used both as a data source and within workflows. However, due to the continuous nature of streaming APIs, there is an important difference in how data is referenced within workflows, especially when using the Result of step X data source.

When initiating a streaming API request within a workflow, Bubble behaves slightly differently on the client side versus the server side:

  • Client-side behavior: The workflow action will appear as "finished" as soon as it begins receiving streamed data from the external API. This allows the workflow to move forward and execute subsequent actions immediately, provided these actions do not rely on the final, non-streamed values from the API request.

  • Server-side behavior: On the server, the workflow action will remain active (blocking) until the streaming API has fully completed and the connection is closed.

For example, if you have a workflow set up like this:

  • Step 1: Send request to ChatGPT (streaming)

  • Step 2: Save the chat message (final text stream) in the database (result of step 1)

The following implications apply:

  • Client-side actions that don't depend on the final API results can proceed without waiting for the stream to fully complete.

  • If an action references the final non-streamed result of the streamed request, the workflow will pause until the streaming has fully completed.

  • Server-side actions will always wait until the streamed API has fully completed, potentially delaying subsequent server-side operations.

Common use case:

  • A frequent scenario is initiating a streamed API call (like ChatGPT), then immediately displaying the incoming streamed data to the user through Bubble's Display data action. This provides users a seamless and responsive experience as the streamed content arrives gradually.

Streaming API data sources

Each response field you configure in the API initialization popup automatically becomes a data source in your app. If you use the field type Text stream, Bubble also creates a few additional underlying data sources to support the streaming functionality:

Text stream

text so far

Text

The text that has been generated so far. This value updates in real time as new data is received from the stream.

full text

Text

The full text. This value is only available after the streaming is done.

Is done

Yes/no

Returns a yes if the stream is done.

Is waiting

Yes/no

Returns a yes if Bubble is awaiting a response.

Is streaming

Yes/no

Returns a yes if the stream is ongoing.

role: The of the message sender. Can be user, assistant, or system.

content: The text itself.

role
message
See Bubble Ambassador and User Manual writer Petter Amlie present the Streaming API feature.