API Connector data sources in Bubble appear as 'Get data from an external API' options that bind directly to Repeating Groups, Text elements, and other UI components. This tutorial covers how to find API data sources after configuring them, bind them to elements, access nested response fields, handle empty and error states, and refresh data on demand.
Overview: Using API Connector Data Sources in Bubble
After configuring API calls in the API Connector, the next step is displaying that data in your app. This tutorial covers how to find your API data sources in Bubble's element data binding, connect them to Repeating Groups and other elements, access nested JSON fields, handle error and empty states, and trigger data refreshes on user demand.
Prerequisites
- A Bubble app with the API Connector plugin configured
- At least one API call set as 'Use as: Data' in the API Connector
- The API call successfully initialized with sample data
- Understanding of Bubble's dynamic data expressions
Step-by-step guide
Find your API data source in element bindings
Find your API data source in element bindings
Select a Repeating Group or any element that needs to display API data. In the Property Editor, click the data source field and look for 'Get data from an external API'. Click it, and a dropdown appears listing all API calls you configured as 'Data' type in the API Connector. Select your API call. If your call requires parameters, Bubble shows input fields for each dynamic parameter. Fill them with static values, dynamic expressions, or references to page elements (like a search input).
Expected result: Your API data source is bound to a Repeating Group or element showing the available response fields.
Display API response data in a Repeating Group
Display API response data in a Repeating Group
After setting the Repeating Group's data source to your API call, set its type of content to the API response type (Bubble creates a type from the initialized response). Inside the RG cell, add elements and bind them to the response fields: Text elements display text/number fields, Image elements display URL fields. Use the 'Current cell's [API type]'s [field]' syntax to access each field. If the API returns a list, the RG automatically iterates. If it returns a single object, set the RG to have 1 row or use a Group instead.
Pro tip: If the API response contains a nested 'results' or 'data' array, you may need to append ':each item's [nested field]' to access the list within the response.
Expected result: A Repeating Group displaying data from the external API with each field bound to the correct element.
Access nested fields in API responses
Access nested fields in API responses
API responses often contain nested objects (like author.name or address.city). After initialization, Bubble flattens these into dot-notation fields that appear in your data binding dropdowns. Select the nested field from the dropdown — it appears as 'response's author's name' or similar chain. For deeply nested structures, you may need to navigate multiple levels. If a nested field does not appear, re-initialize the API call with a response that includes that field — Bubble only maps fields present during initialization.
Expected result: Nested API response fields are accessible through Bubble's chained data reference syntax.
Handle empty responses and error states
Handle empty responses and error states
Add conditional visibility to handle cases where the API returns no data. On your Repeating Group, add a conditional: when This Repeating Group's List of [type]:count is 0, show an 'empty state' Group with a message like 'No results found'. For error handling, check if the API Connector's error handling is enabled. Display a Text element that shows an error message when the API response contains an error field. Add a 'Try Again' button that triggers a page refresh or re-runs the API call by changing a custom state that the data source depends on.
Expected result: Empty and error states are handled gracefully with user-friendly messages and retry options.
Refresh API data on demand
Refresh API data on demand
API Connector data sources in Bubble auto-refresh when the page loads but do not auto-update like database searches. To refresh data on demand, create a custom state on the page called refresh_trigger (type number, default 0). Add the refresh_trigger as an unused parameter in your API call (Bubble re-fetches when parameters change). When the user clicks a Refresh button, increment the refresh_trigger state by 1. This forces Bubble to re-call the API and update the displayed data.
Pro tip: Use this same technique to refresh data after the user submits a form that should change the API results.
Expected result: A Refresh button that triggers the API to re-fetch and update displayed data without a full page reload.
Complete working example
1API DATA SOURCE USAGE SUMMARY2===============================34BINDING API DATA:5 Repeating Group data source:6 → Get data from an external API7 → Select: [Your API Call Name]8 → Set parameters (dynamic or static)9 → Type of content: [API response type]1011 Cell element bindings:12 Text: Current cell's [API type]'s title13 Image: Current cell's [API type]'s image_url14 Nested: Current cell's [API type]'s author's name1516NESTED FIELD ACCESS:17 API returns: { data: { users: [{ name, email }] } }18 Bubble mapping: response's data's users19 Each item: Current cell's user's name2021EMPTY STATE HANDLING:22 Conditional on RG:23 When list count = 0 → show empty state Group24 Error state:25 When response's error is not empty → show error message2627REFRESH PATTERN:28 Custom state: refresh_trigger (number, default 0)29 API call parameter: _refresh = refresh_trigger30 Refresh button workflow:31 Set state: refresh_trigger = refresh_trigger + 132 (Changing the parameter forces Bubble to re-fetch)3334API CALL TYPES:35 Data: appears in 'Get data from external API'36 Use for: displaying data in elements37 Action: appears in workflow plugin actions38 Use for: triggering operations (POST, PUT, DELETE)Common mistakes when findding and use data sources created with the API Connector in
Why it's a problem: Setting the API call as 'Action' instead of 'Data' and wondering why it does not appear in data sources
How to avoid: In the API Connector, set the call to 'Use as: Data' for calls that should display data in elements
Why it's a problem: Not re-initializing after the API response structure changes
How to avoid: Re-initialize the API call whenever the external API's response structure changes to update the field mapping
Why it's a problem: Expecting API data sources to auto-update like database searches
How to avoid: Use the refresh_trigger custom state pattern to force re-fetching when the user needs updated data
Best practices
- Set API calls to 'Use as: Data' for display purposes and 'Use as: Action' for workflow operations
- Re-initialize API calls whenever the response structure changes
- Handle empty and error states with conditional visibility and user-friendly messages
- Use the refresh_trigger pattern to enable on-demand data refresh
- Initialize API calls with complete sample responses to capture all possible fields
- Add loading indicators while API data is being fetched
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I configured an API call in Bubble's API Connector but I cannot find how to display the data in a Repeating Group. The API returns a nested JSON response with a 'results' array. Can you help me bind it correctly?
Help me display data from my API Connector call in a Repeating Group. The API returns nested JSON and I need to show specific fields from the response in my UI elements.
Frequently asked questions
Why does my API data source not appear in the dropdown?
The API call must be set to 'Use as: Data' in the API Connector. If it is set to 'Action', it only appears in workflow plugin actions, not in element data sources.
How do I pass user input as an API parameter?
When setting the data source, click the parameter field and select a dynamic expression referencing a page element, like 'Input Search's value' or 'Dropdown City's value'.
Can I cache API responses to reduce calls?
Bubble does not natively cache API responses. You can implement caching by saving API data to a Bubble Data Type and checking the cached version's age before making a new API call.
Why are some API fields missing after initialization?
Bubble only maps fields present in the initialization response. If the sample data was incomplete (missing optional fields), those fields will not appear. Re-initialize with a more complete response.
Can I use API data in conditional formatting?
Yes. Once an element's data source is set to API data, you can reference API fields in conditional expressions just like database fields.
Can RapidDev help with complex API integrations?
Yes. RapidDev can configure API Connector integrations including nested response handling, error management, caching strategies, and complex data transformations.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation