Retool Getting Started: Account Setup & First API Call (2026)

Getting started overview

Getting started with Retool involves establishing an account, connecting to a data source, and then constructing a basic application component that interacts with that source. This process typically begins with signing up for a Retool instance, which can be cloud-hosted or self-hosted, depending on organizational requirements. A key step is configuring a resource, which acts as a connection to an external database, API, or service. Once a resource is set up, developers can begin to build queries and visual components within the Retool editor to fetch and display data or perform actions.

Retool is designed to simplify the development of internal applications by abstracting much of the frontend development work through a drag-and-drop interface. However, it also provides the flexibility to write custom JavaScript for more complex logic and data manipulation. The initial setup focuses on ensuring connectivity to your chosen data backend, as this forms the foundation for any application built on the platform. Retool supports a wide array of integrations, from SQL databases like PostgreSQL and MySQL to NoSQL databases such as MongoDB, and various REST or GraphQL APIs Retool data source connections.

The following table outlines the key steps to initiate your Retool development:

Create an account and get keys

To begin with Retool, the first step is to create an account. Retool offers a free tier for up to 5 users, which is suitable for initial exploration and small projects. For larger teams or more advanced features, paid plans are available, starting with the Team plan. During the signup process, users typically provide an email address and set up a password. There is no specific API key or token generated immediately upon account creation in the same way a traditional API service might provide one. Instead, access to external data sources is managed through resource configurations within the Retool platform itself.

Retool functions as an application builder that connects to your existing data sources. Therefore, the "keys" you'll primarily manage are the credentials for those external services, databases, or APIs. For example, when connecting to a REST API, you would input the API's base URL and any necessary authentication headers (such as an API key or OAuth 2.0 token) directly into Retool's resource configuration. Retool securely stores these credentials, allowing your applications to make authenticated requests without exposing the keys directly in client-side code.

For self-hosted Retool instances, the setup involves deploying Retool using Docker or Kubernetes. In this scenario, managing access and security involves configuring the underlying infrastructure, network access, and potentially integrating with existing identity providers. While this offers greater control and can be integrated into existing security frameworks, it also introduces more operational overhead compared to the cloud-hosted option.

When connecting to a database, you would provide connection string details, including host, port, database name, username, and password. For OAuth 2.0-protected APIs, Retool guides you through the process of setting up an OAuth client within Retool and configuring the necessary redirect URLs with the external service. For instance, connecting to a Google API might involve configuring an OAuth client in the Google Cloud Console API & Services dashboard and then using the client ID and secret within Retool's resource setup.

Your first request

Making your first request in Retool involves two primary steps: configuring a resource and then building a query against that resource within an application. This example will focus on connecting to a public REST API, as it demonstrates the core concept of fetching data from an external service.

Step 1: Create a new resource

1. Navigate to the Retool dashboard.
2. Click on Resources in the left sidebar.
3. Click Create new and select REST API from the list of available resource types.

4. Configure the REST API resource:

   • Name: PublicJokeAPI
   • Base URL: https://v2.jokeapi.dev/ (This is a public API for demonstration purposes, requiring no authentication.)
   • Authentication: Select "No authentication" for this example. For production scenarios, you would configure API key, OAuth 2.0, or other methods as required by your API Retool REST API resource configuration.
   • Click Create resource.

Step 2: Create a new application and query

1. Return to the Retool dashboard and click Create new > App.
2. Give your app a name, e.g., JokeDisplayApp.
3. In the Retool app editor, locate the + Query button at the bottom of the screen and click it.

4. Configure your query:

   • Name: fetchJoke
   • Resource: Select PublicJokeAPI from the dropdown.
   • Action type: Set to GET.
   • URL: In the URL field, append joke/Any?type=single to the base URL. The full URL will effectively be https://v2.jokeapi.dev/joke/Any?type=single, which requests a single joke of any category.
   • Trigger this query when inputs change: Uncheck this for now to manually trigger the first request.
   • Click "Save & Run".

5. Observe the result:

   • The query results will appear in the "State" panel on the right, under fetchJoke.data. You should see a JSON object containing a joke.

Step 3: Display the data in a UI component

1. Drag a Text component from the right-hand components panel onto the canvas.
2. Select the Text component. In the inspector panel on the right, locate the Value property.
3. Enter {{ fetchJoke.data.joke }}. This uses Retool's JavaScript templating syntax to reference the joke property from the data returned by your fetchJoke query.
4. The text component will now display the fetched joke.

This sequence demonstrates connecting to an API, making a GET request, and displaying the retrieved data within a basic UI component, forming the fundamental building blocks of a Retool application.

Common next steps

After successfully making your first request and displaying data, several common next steps can enhance your Retool application:

• Add more UI components: Explore Retool's extensive library of components, such as tables, forms, buttons, and charts, to build more interactive user interfaces Retool UI components documentation. For instance, you could add a button to trigger the fetchJoke query again, retrieving a new joke.
• Connect to a database: Most internal tools interact with databases. Configure a new resource for your SQL (e.g., PostgreSQL, MySQL) or NoSQL (e.g., MongoDB, Firebase) database. You can then write queries to read, insert, update, or delete data directly from your app. For example, connecting to a Firebase Cloud Firestore database would involve creating a Firebase resource and then using its query builder to interact with collections and documents.
• Build forms for data input: Use form components (Text Input, Dropdown, Datepicker) to allow users to input data. Connect these form inputs to queries that update or insert data into your database or API. Learn about building forms in Retool.
• Implement user authentication and permissions: For applications that require controlled access, configure user authentication. Retool supports various methods, including Google SSO, SAML, and custom authentication, along with role-based access control to define what different users can see and do Retool user management documentation.
• Write custom JavaScript logic: While Retool's visual builder is powerful, complex scenarios often require custom logic. Use JavaScript within queries, transformers, or event handlers to manipulate data, perform conditional actions, or integrate with other services. For example, you might use JavaScript to dynamically filter a table based on user input or to format data before displaying it.
• Deploy and share your application: Once your application is ready, you can deploy it for your internal team. Retool provides options to publish applications and manage access permissions for different user groups.
• Explore Retool Workflows: For automating backend processes, consider using Retool Workflows. This allows you to chain together API calls, database operations, and custom logic to create scheduled tasks or respond to webhooks Retool Workflows overview.

Troubleshooting the first call

When your first Retool query doesn't work as expected, several common issues can arise. Debugging involves checking the resource configuration, query parameters, network connectivity, and handling of responses.

• Resource configuration errors:
  • Incorrect Base URL: Double-check the base URL of your REST API or database host. A common mistake is a typo or missing https://.
  • Authentication issues: If your API requires authentication (e.g., API key, OAuth 2.0, Bearer token), ensure the credentials are correct and properly configured in the resource settings. Verify that the authentication header name and value match the API's requirements. For OAuth, confirm that the Redirect URL configured in the external service matches Retool's generated URL.
  • Network access: If Retool is self-hosted or connecting to an internal database, ensure that Retool's instance has network access to the target API or database. Firewall rules or VPC configurations might block the connection.
• Query-specific errors:
  • Incorrect endpoint or path: Verify that the URL path appended to the base URL in your query is correct according to the API's documentation.
  • Missing or incorrect parameters: Check if required query parameters, headers, or body data are correctly supplied. Pay attention to case sensitivity and data types.
  • HTTP method mismatch: Ensure the HTTP method (GET, POST, PUT, DELETE) in your query matches what the API expects for that endpoint.
  • Syntax errors in JavaScript: If you're using JavaScript templating ({{ }}) within your query, ensure there are no syntax errors. Retool's editor often highlights these, but a subtle mistake can prevent the query from running.
• Inspecting responses and errors:
  • Query History: In the Retool editor, the "Query History" tab at the bottom will show details of past query runs, including the request sent, the response received, and any errors. This is the primary place to diagnose issues.
  • Network Tab (Browser Developer Tools): For client-side queries or issues related to Retool's UI loading, your browser's developer tools (F12) network tab can reveal if network requests are failing or returning unexpected HTTP status codes (e.g., 401 Unauthorized, 404 Not Found, 500 Internal Server Error). Understanding HTTP status codes is fundamental for API debugging, as detailed in the Mozilla Developer Network HTTP status code reference.
  • Transformer or event handler errors: If you have JavaScript transformers or event handlers attached to your query, errors within these scripts can prevent data from being processed correctly or displayed. Check the browser console for JavaScript errors.
• Permissions: Ensure the credentials used have the necessary permissions to perform the requested operation on the external data source. A database user might only have read access when the application attempts to write data.