# How to Integrate Retool with UserTesting

- Tool: Retool
- Difficulty: Intermediate
- Time required: 25 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to UserTesting by creating a REST API Resource with UserTesting's API base URL and your API key. Build queries in the Retool query editor to pull test results, participant feedback, and session metadata — creating a UX research management dashboard that tracks test status, organizes findings by product area, and shares insights with stakeholders without requiring UserTesting admin access.

## Why Connect Retool to UserTesting?

UX research teams run dozens of UserTesting studies simultaneously across different product areas, but tracking the status of all active tests, organizing results, and routing insights to the right product teams is often managed through spreadsheets or email threads. Connecting UserTesting to Retool lets you build a centralized research operations dashboard that surfaces test status, participant completion counts, and result availability in real time — without requiring everyone on the product team to have UserTesting login access.

A Retool UserTesting panel allows research managers to view all active and completed tests in a single table, filter by product area or research theme, and click into any test to see participant responses and key metrics. Product managers and designers can access a read-only version of this dashboard to stay informed about research findings as they become available, accelerating the research-to-decision cycle without burdening the research team with manual status update emails.

Combining UserTesting data with other Retool resources unlocks more sophisticated use cases: correlating research findings with quantitative data from your analytics platform, linking test results to specific product roadmap items tracked in Jira or Asana, or building a research repository that tags and organizes insights by user segment, feature area, and research question. Retool's server-side proxy ensures all API calls to UserTesting are secure and that participant data never passes through the client browser.

## Before you start

- A UserTesting account with API access enabled (UserTesting API is available on Professional and Enterprise plans)
- A UserTesting API key from your account settings or provided by your UserTesting account manager
- Basic familiarity with the Retool app builder — query editor and Table/Form components
- A Retool account (Cloud or self-hosted) with permission to add Resources
- Optional: a Retool Database table for storing analyst notes and insight tags if building a research repository

## Step-by-step guide

### 1. Obtain a UserTesting API key

Log into your UserTesting account at https://app.usertesting.com. Navigate to your account settings by clicking your name or avatar in the top-right corner, then selecting Account Settings or Integrations from the dropdown. Look for an API section or Developer settings panel — this is where UserTesting displays your API key and allows you to regenerate it.

If you do not see an API section in your account settings, your UserTesting plan may not include API access. UserTesting's REST API is typically available on Professional and Enterprise tiers. Contact your UserTesting account manager or customer success representative to request API access — they can enable it and provide you with the API key and documentation for your specific API version.

Once you have your API key, note the following for Retool configuration:
- Your API key string
- The base URL for UserTesting's API (typically https://api.usertesting.com/v1/ or a version-specific URL in your documentation)
- The authentication method (usually the API key is sent as an 'X-Api-Key' header or 'Authorization: Bearer' header)

Do not share your API key — it provides access to all your UserTesting tests and participant data. You will store it in a Retool configuration variable rather than pasting it directly into the resource form.

**Expected result:** You have a UserTesting API key and base URL ready to configure in Retool.

### 2. Create a REST API Resource in Retool for UserTesting

First, save your UserTesting API key as a secure configuration variable. Navigate to Settings (gear icon in the Retool sidebar) → Configuration Variables. Click Add Variable, name it USERTESTING_API_KEY, paste your API key as the value, check the 'Secret' checkbox to hide it from non-admin users, and click Save.

Next, go to the Resources tab in the Retool sidebar and click Add Resource. Type 'REST' in the search field and select REST API. In the configuration form:

- Name: enter 'UserTesting API'
- Base URL: enter your UserTesting API base URL, for example https://api.usertesting.com/v1/

In the Headers section (not the Authentication section), add the API key header that UserTesting requires. The most common pattern is:
- Header name: X-Api-Key (or Authorization if UserTesting uses Bearer token format)
- Header value: {{ retoolContext.configVars.USERTESTING_API_KEY }}

Also add: 'Accept' → 'application/json' and 'Content-Type' → 'application/json' as global headers to ensure all requests receive and send JSON.

Leave the Authentication dropdown set to 'None' if you are using a header-based API key (most common for UserTesting). Click Save Changes. Your UserTesting resource is now available for building queries.

**Expected result:** The UserTesting REST API Resource appears in your Resources list. A test query returns a 200 OK response with test data in JSON format.

### 3. Build a query to list all UserTesting tests

Open or create a Retool app. In the Code panel at the bottom, click + to create a new query. Select your UserTesting API resource from the Resource dropdown. The query editor displays REST API mode.

Configure the query:
- Method: GET
- Path: /tests
- Query Parameters:
  - status: {{ statusFilter.value || '' }} — filter by test status (draft, live, complete). Leave empty to fetch all.
  - page: {{ pagination.page || 1 }}
  - per_page: {{ pagination.pageSize || 25 }}
  - sort_by: 'created_at'
  - sort_direction: 'desc'

In the Advanced tab, add a JavaScript transformer to normalize the response. UserTesting API responses typically wrap the test list in a 'tests', 'data', or 'results' key with additional metadata.

Set the query name to 'testsQuery' and its Run mode to 'Automatically run when inputs change' to support filtering and pagination. Drag a Table component from the Component panel and set its Data to {{ testsQuery.data }}. Configure columns: test_name, status, participant_target, completed_sessions, and completion_rate. Set column types appropriately — completion_rate as a percentage, created_date formatted as a localized date string.

Add a Select component with options for status filtering: All, Draft, Live, Complete. Bind the Select's value to the status query parameter. When the Select changes, the tests query automatically re-runs with the new filter.

```
// Transformer to normalize UserTesting tests list response
const response = data;
const tests = response.tests || response.data || response.results || (Array.isArray(response) ? response : []);
return tests.map(t => ({
  id: t.id,
  testName: t.name || t.title || 'Untitled Test',
  status: t.status || 'unknown',
  testType: t.test_type || t.methodology || 'unmoderated',
  participantTarget: t.participant_count || t.session_count_target || 0,
  completedSessions: t.completed_session_count || t.completed_count || 0,
  completionRate: t.participant_count
    ? Math.round(((t.completed_session_count || 0) / t.participant_count) * 100) + '%'
    : 'N/A',
  createdDate: t.created_at ? new Date(t.created_at).toLocaleDateString() : 'N/A',
  productArea: (t.tags || []).join(', ') || 'Untagged',
  resultsUrl: t.url || t.share_url || ''
}));
```

**Expected result:** A Table in your Retool app displays all UserTesting tests with status, participant progress, and completion rates. Filtering by status updates the table instantly.

### 4. Fetch session-level results for a selected test

To build a drill-down view that shows individual participant sessions for any selected test, create a second query that fetches session data when a test row is selected in the tests table.

In the Code panel, click + to add a new query. Select your UserTesting API resource. Configure:
- Method: GET
- Path: /tests/{{ testsTable.selectedRow.id }}/sessions (adjust path to match your UserTesting API's session endpoint)
- Additional Query Parameters: 'status' → 'completed' to show only completed sessions

In the query's Settings, set it to only run 'When inputs change' and enable 'Only run when inputs have valid values' — this prevents the query from firing when no test row is selected (which would send an undefined test ID).

Add a JavaScript transformer to extract session metrics from the response. UserTesting sessions typically include a participant identifier, session duration, task ratings, and a text summary or transcript.

Drag a second Table below the main tests table and set its Data to {{ sessionsQuery.data }}. Configure columns: participant_id, duration_minutes, overall_rating, task_completion_rate, and session_date. Select a session row to show the full feedback in a Text component or Modal below the table.

For the overall_rating column, set its column type to 'Rating' (Retool's star rating column type) to visualize the 1-5 scale visually rather than as a number.

```
// Transformer for UserTesting session results
const response = data;
const sessions = response.sessions || response.data || response.results || (Array.isArray(response) ? response : []);
return sessions.map(s => ({
  sessionId: s.id,
  participantId: s.participant_id || s.tester_id || 'Unknown',
  durationMinutes: s.duration_seconds ? Math.round(s.duration_seconds / 60) : 'N/A',
  overallRating: s.rating || s.overall_score || null,
  taskCompletionRate: s.task_completion_rate
    ? Math.round(s.task_completion_rate * 100) + '%'
    : 'N/A',
  sessionDate: s.completed_at ? new Date(s.completed_at).toLocaleDateString() : 'N/A',
  summary: s.summary || s.description || s.feedback || '',
  highlights: (s.highlights || []).map(h => h.text || h).join(' | ') || 'No highlights'
}));
```

**Expected result:** Selecting a test in the first table triggers the sessions query. The second table populates with individual participant sessions. Selecting a session row displays the participant's feedback text and rating details.

### 5. Build a stakeholder-facing research digest and set up result notifications

To notify stakeholders automatically when new UserTesting results become available, set up a Retool Workflow that checks daily for newly completed tests and posts a summary to a Slack channel or sends an email digest.

Navigate to the Workflows section in Retool's home page sidebar. Click New Workflow. Click Add Trigger and select Schedule — set it to run every day at 9:00 AM.

Add a Resource Query block targeting your UserTesting API resource. Configure it to fetch tests with status=complete and sort by updated_at descending, with a filter for tests completed in the last 24 hours (or since the last workflow run). You can use query parameters like: created_after={{ new Date(Date.now() - 86400000).toISOString() }}.

Add a JavaScript Code block that formats the test results into a readable summary string — listing each completed test name, participant count, and a link to the results page.

Add a final Resource Query block using your Slack resource (or SendGrid/email resource if preferred). Configure it to post the formatted summary to your #research-updates Slack channel or send an email to stakeholders. Include a count of newly completed tests and a bulleted list of test names with completion stats.

Publish the Workflow with Publish Release. For complex integrations involving multiple Resources and Workflows, RapidDev's team can help architect and build your Retool solution.

```
// Format newly completed tests into a Slack-ready summary
const tests = block1.data.tests || block1.data || [];
if (tests.length === 0) {
  return { message: null, shouldNotify: false };
}
const lines = tests.map(t =>
  `• *${t.name || t.title}* — ${t.completed_session_count || 0} sessions completed. <${t.url}|View results>`
);
return {
  shouldNotify: true,
  message: `:test_tube: *${tests.length} UserTesting ${tests.length === 1 ? 'study' : 'studies'} completed today:*\n` + lines.join('\n')
};
```

**Expected result:** The Workflow is published and active. On days when UserTesting studies are completed, a summary message appears in the configured Slack channel with links to the results. On days with no completions, nothing is posted.

## Best practices

- Store your UserTesting API key in a Retool configuration variable marked as secret (Settings → Configuration Variables) rather than entering it directly in the resource header configuration, to protect it from non-admin Retool users.
- Use Retool's query caching on your tests list query (cache for 15-30 minutes) since test status changes infrequently during the day — this prevents unnecessary API calls on every dashboard load.
- Set your sessions detail query to Manual trigger mode and only fire it when a test row is selected, using 'Only run when inputs have valid values' — this avoids sending requests with undefined test IDs when the page first loads.
- Combine UserTesting tags with a product_area filter to keep the research tracker organized — add a text column for tags in the Table and filter on it with a Retool text input or multi-select component.
- Build a separate read-only Retool app for stakeholders (product managers, designers) that shows only completed tests with curated summaries — share this as a public Retool app link rather than granting full UserTesting admin access.
- Use Retool Database to store analyst notes, insight tags, and key findings linked to UserTesting session IDs, creating a research repository that persists beyond what the UserTesting API exposes.
- Test all queries with a completed test from last month before wiring up live tests — this gives you real data to validate transformers and UI layouts without depending on tests currently in flight.

## Use cases

### Build a UX research queue and status tracker

Create a Retool dashboard that fetches all UserTesting tests for your team, displays them in a Table with status (draft, live, complete), participant count, completion rate, and a link to the UserTesting results page. Research coordinators can filter by product area, test type (moderated vs. unmoderated), and date range. A progress bar column visualizes completion rate for each test at a glance.

Prompt example:

```
Build a research tracker that fetches all tests from the UserTesting API, displays them in a Table with columns for test_name, status, participant_target, completed_sessions, completion_rate, and created_date. Add filters for status and product_area tags. Show a progress bar in the completion_rate column using Retool's column formatting.
```

### Participant feedback viewer and insight tagging panel

Build a Retool app where research team members can select a completed UserTesting test, view individual participant session summaries and ratings, and add internal tags or notes to each session for later analysis. The panel pulls session-level data from UserTesting's API and stores tags in a Retool Database table, creating a lightweight research repository that links raw UserTesting data with team-generated insights.

Prompt example:

```
Create a session feedback panel where selecting a test from a dropdown loads participant sessions from the UserTesting API. Display each session in a Table with participant_id, duration, rating, and task completion. Clicking a row shows the session summary text. Add a text input and save button to store analyst notes for each session in a Retool Database table.
```

### Stakeholder research digest dashboard

Build a read-only Retool app for product managers and designers that shows a curated summary of recently completed UserTesting studies grouped by product area. Each study card shows the research question, key findings (pulled from the test description or analyst notes stored in your database), and a link to the full UserTesting results. This replaces manually written research digest emails with a self-service dashboard stakeholders can check directly.

Prompt example:

```
Build a research digest dashboard that fetches completed tests from UserTesting API (status=complete, sorted by completion_date desc), groups them by product_area tag, and displays each as a Card component with test_name, key_finding text (from a linked database table), completion_date, and a 'View Results' button linking to the UserTesting URL.
```

## Troubleshooting

### API requests return 401 or 403 errors despite the correct API key in the resource header

Cause: The header name may not match exactly what UserTesting's API expects (common variants are X-Api-Key, X-API-KEY, Authorization: Bearer, or Api-Key), or the API key may have been revoked or is scoped to a different workspace.

Solution: Review your UserTesting API documentation for the exact header name and format. Try switching between 'X-Api-Key', 'Authorization: Bearer your_key', and 'Api-Key' header configurations in the Retool resource. If problems persist, regenerate your API key in UserTesting account settings and update the Retool configuration variable with the new key.

### Tests list returns data but session results query returns 404 Not Found for test IDs

Cause: The session endpoint path may differ from what you configured — UserTesting API paths vary by version (e.g., /tests/{id}/sessions vs. /studies/{id}/responses vs. /test_sessions?test_id={id}).

Solution: Consult your UserTesting API documentation for the exact path to retrieve sessions for a given test. Open a query, run the base /tests endpoint to confirm a valid test ID, then try variations of the session path with that ID in Retool's query runner. Check the API response headers for an API version indicator that may point to correct documentation.

### Participant data fields like summary or feedback_text are empty or null in the API response

Cause: UserTesting may keep detailed session content (transcripts, highlights, summaries) in separate sub-resources that require additional API calls per session, rather than including them in the session list response.

Solution: Check if UserTesting's API has a separate endpoint for session details (e.g., /sessions/{session_id}/highlights or /sessions/{session_id}/transcript). Create a detail query that runs when a session row is selected, fetching the full session record including participant notes and feedback text. Display this in a detail panel that expands below the sessions table.

### Workflow notifications send empty messages because no tests match the 'completed today' filter

Cause: The date filter for 'created in the last 24 hours' may not match UserTesting's timestamp format, or completed tests may be timestamped at the time the last session was submitted rather than when you check.

Solution: Broaden the time window in your Workflow query filter from 24 hours to 48 hours and add deduplication logic in a Code block to avoid notifying about the same test twice. Alternatively, store the last-notified test IDs in a Retool Database table and filter against those in your Workflow's Code block.

## Frequently asked questions

### Does UserTesting provide an API for all plan tiers, or only Enterprise?

UserTesting's REST API is primarily available on their Professional and Enterprise plans. Basic individual accounts typically do not include API access. Contact UserTesting's sales team or your account manager to confirm whether your current plan includes API access and to obtain API credentials and endpoint documentation.

### Can I access UserTesting video recordings through the API?

UserTesting's API may expose video URLs for completed sessions depending on your plan and API version. Check your session response object for a 'video_url' or 'recording_url' field. If available, display it in Retool using a Video component or as a clickable link — note that video access may require a session-authenticated URL that expires after a short period.

### How do I filter UserTesting results by product area or team in Retool?

UserTesting allows you to add tags or labels to tests. In your Retool tests list query, transform the tags array into a comma-separated string and display it as a column. Add a Retool text input or multi-select component for tag filtering and use a JavaScript query to filter the transformed data client-side, or pass the tag as a query parameter if the UserTesting API supports server-side tag filtering.

### Can Retool display UserTesting session clips and highlights alongside participant data?

If the UserTesting API exposes clip URLs or highlight timestamps in the session response, you can display them in Retool as clickable links. For a richer experience, embed the UserTesting results page in a Retool IFrame component — though this requires users to be logged into UserTesting for the embedded content to load.

### Is participant personal information from UserTesting safe when proxied through Retool?

Retool's REST API Resource proxies all requests through Retool's server-side backend — participant data never passes through the browser client. For additional security, restrict your Retool app to specific Retool groups (UX research team only) using Retool's app access controls, and avoid displaying personally identifiable participant data in columns visible to stakeholders who do not need it.

---

Source: https://www.rapidevelopers.com/retool-integrations/usertesting
© RapidDev — https://www.rapidevelopers.com/retool-integrations/usertesting