# How to Integrate Retool with Getty Images API

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

## TL;DR

Connect Retool to the Getty Images API by creating a REST API Resource using OAuth 2.0 client credentials with your Getty API key and secret. Build media procurement dashboards for newsrooms and marketing teams that search editorial and creative images, manage download boards, track license compliance, and monitor usage across departments.

## Build a Getty Images Media Management Panel in Retool

Getty Images' website is optimized for individual creative searches, but media procurement managers at newsrooms, agencies, and marketing departments need operational views that Getty's native interface doesn't provide: all licensed images across all projects and departments, license expiration tracking for images used in long-running campaigns, usage compliance reporting showing which departments are downloading images without proper licensing, or a centralized board management tool for curating approved images for an upcoming project. Retool lets you build these internal tools directly against the Getty Images API.

The Getty Images API v3 provides access to image search (with editorial and creative filters, orientation, color palette, and composition), individual asset metadata, download URL retrieval, and board (collection) management for organizing licensed assets. Authentication uses OAuth 2.0 client credentials: you send your API key and secret to obtain a time-limited Bearer token that authorizes all subsequent API calls.

The most valuable Retool use case for Getty Images is a media procurement dashboard used by newsroom editors or agency creative directors. They can search Getty's editorial archive with specific filters (date range, photographer, event, location), add candidate images to a board, track which images have been licensed and downloaded, and generate a compliance report showing image usage versus license terms — all from a single internal tool without individual team members needing their own Getty accounts.

## Before you start

- A Getty Images developer account with API access (register at https://developers.gettyimages.com)
- An approved Getty Images API application with client ID and client secret
- A Getty Images licensing agreement for download access (search-only access has different permissions than download access)
- A Retool account with permission to create Resources
- Basic familiarity with Retool's query editor and Gallery or Table components

## Step-by-step guide

### 1. Obtain Getty Images API credentials and access token

Navigate to https://developers.gettyimages.com and sign in with your Getty Images account. Go to the Applications section and create a new application. Provide an application name, description, and intended use case. Getty Images reviews applications before granting API access — commercial applications may require additional review.

Once approved, your application will have a Client ID and Client Secret (sometimes labeled API Key and API Secret). Copy both values.

To obtain an OAuth 2.0 access token, make a POST request to https://authentication.gettyimages.com/oauth2/token with:
- Content-Type: application/x-www-form-urlencoded
- Body: grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

The response includes an access_token (Bearer token) and expires_in (seconds until expiration, typically 1800 seconds = 30 minutes).

Store your credentials in Retool Configuration Variables (Settings → Configuration Variables): GETTY_CLIENT_ID, GETTY_CLIENT_SECRET (both marked as secret), and GETTY_ACCESS_TOKEN. You will need to refresh this token periodically as it expires every 30 minutes.

**Expected result:** You have Getty Images API credentials and a valid access token stored in Retool Configuration Variables.

### 2. Create the Getty Images REST API Resource in Retool

In Retool, navigate to the Resources tab and click Add Resource. Select REST API from the connector list.

Name: Getty Images API

Base URL: https://api.gettyimages.com/v3

Authentication: Select Bearer Token. In the Token field, enter {{ retoolContext.configVars.GETTY_ACCESS_TOKEN }}. This references the access token stored in your configuration variable.

Add a default header: Content-Type: application/json.

Click Create Resource. Test with a simple query: GET /images/search?phrase=mountain&fields=id,title,caption&page=1&page_size=5. If this returns a JSON object with images array containing image objects with IDs and titles, authentication is working correctly.

Note: The Getty Images API returns different content based on your licensing agreement. The search endpoint is available to all API users. Download URLs (GET /images/{id}/downloads) require a commercial licensing agreement. The URI returned for image downloads is time-limited (typically valid for 10 minutes after retrieval).

If you receive 401 on any query, the access token has expired (tokens last only 30 minutes). Refresh it by running the token endpoint request and updating the GETTY_ACCESS_TOKEN configuration variable.

**Expected result:** The Getty Images REST API Resource is created. GET /images/search?phrase=test&page_size=5 returns image results with IDs, titles, and thumbnail URIs.

### 3. Build the image search panel with filters and thumbnails

Create a searchImages query: GET /images/search with the following URL parameters:
- phrase: {{ input_search.value }}
- fields: id,title,caption,display_sizes,asset_family,collection_name,date_taken,photographer
- page: {{ Math.floor(galleryComponent.currentPage * galleryComponent.pageSize / 25) + 1 }}
- page_size: 25
- sort_order: best_match (also: most_popular, newest, oldest)
- editorial_segments: news (also: entertainment, sport, archival — filter to editorial subcategories)
- asset_family: editorial (also: creative — separates editorial from stock)
- orientations: {{ select_orientation.value || '' }} (values: horizontal, vertical, square)

The fields parameter controls which data is returned. display_sizes is required to get thumbnail URLs for preview — it returns an array of size objects with name (comp, preview, thumb) and uri.

Create a JavaScript transformer to extract thumbnail URIs:
const images = data?.images || [];
return images.map(img => ({ id: img.id, title: img.title, caption: img.caption?.substring(0, 200) || '', thumb: img.display_sizes?.find(s => s.name === 'thumb')?.uri || '', preview: img.display_sizes?.find(s => s.name === 'preview')?.uri || '', photographer: img.photographer, collection: img.collection_name, date: img.date_taken ? new Date(img.date_taken).toLocaleDateString() : '', family: img.asset_family }));

Display search results using a Retool Table with an Image column type bound to the thumb field to show thumbnail previews inline.

```
// Transformer for Getty Images search results
const images = data?.images || [];
return images.map(img => ({
  id: img.id,
  title: img.title || 'Untitled',
  caption: (img.caption || '').substring(0, 200),
  thumb_url: img.display_sizes?.find(s => s.name === 'thumb')?.uri || '',
  preview_url: img.display_sizes?.find(s => s.name === 'preview')?.uri || '',
  comp_url: img.display_sizes?.find(s => s.name === 'comp')?.uri || '',
  photographer: img.photographer || 'Unknown',
  collection: img.collection_name || '',
  asset_family: img.asset_family || '',
  date_taken: img.date_taken ? new Date(img.date_taken).toLocaleDateString() : '',
  asset_id_copy: img.id // for clipboard copy action
}));
```

**Expected result:** The image search panel displays results in a Table with inline thumbnail previews, photographer credit, collection name, and date taken. Filters for asset family and orientation narrow results.

### 4. Manage download boards and licensed asset tracking

Getty Images boards are curated collections for organizing images during the editorial or creative selection process. Create a getBoards query: GET /boards to list all boards for the authenticated account. Each board has: id, name, description, date_created, and asset_count.

Create a getBoardImages query: GET /boards/{{ select_board.value }}/assets to fetch images in the selected board. Each asset has asset_id and date_added.

Create an addToBoard query: PUT /boards/{{ select_board.value }}/assets with body: { "asset_ids": {{ JSON.stringify([table_results.selectedRow.data.id]) }} }. This adds the selected image to the chosen board. Bind this to an 'Add to Board' button.

Create a createBoard query: POST /boards with body: { "name": "{{ input_boardName.value }}", "description": "{{ input_boardDescription.value }}" }. Add a Create Board button that opens a Modal with these fields.

For download tracking (requires commercial license agreement), create a getDownloads query: GET /downloads with parameters page_size: 100 and sort_order: newest_first. The downloads endpoint returns all images downloaded by your account with: asset_id, date_time (download timestamp), product_id, and product_type (subscription, on_demand, etc.). Use this to build the license compliance report.

```
// Transformer for download history (license tracking)
const downloads = data?.downloads || [];
const today = new Date();

return downloads.map(dl => {
  const downloadDate = new Date(dl.date_time);
  const daysSince = Math.floor((today - downloadDate) / 86400000);

  // Subscription images: typically licensed for usage in content published within subscription period
  // On-demand: single use license
  const licenseType = dl.product_type || 'unknown';
  const isExpired = licenseType === 'easyaccess' && daysSince > 365; // example: editorial easy access 1-year window

  return {
    asset_id: dl.asset_id,
    downloaded_at: downloadDate.toLocaleDateString(),
    days_since: daysSince,
    product_type: licenseType,
    product_id: dl.product_id || '',
    license_status: isExpired ? 'Review Required' : 'Active',
    thumb_url: '' // fetch separately if needed
  };
});
```

**Expected result:** Boards are listed in a Select component. Selecting a board shows its images. The Add to Board button adds selected search results to the active board. Download history shows all licensed images with download dates.

### 5. Build the license compliance report and image detail view

Create an image detail view for the selected search result. When a user clicks a row in the search Table, show a detail Container on the right side with:
- The comp (watermarked preview) image for visual confirmation
- Full caption text
- Photographer name and credit line
- Collection name and asset family (editorial vs. creative)
- Available sizes and file formats
- License types available for this image
- An asset ID field with a copy button for procurement reference

Fetch full image details: GET /images/{{ table_results.selectedRow.data.id }}?fields=id,title,caption,photographer,collection_name,date_taken,editorial_segments,license_model,display_sizes,download_sizes.

For the license compliance report, create a compliance summary using the getDownloads data transformer. Group downloads by month using a JavaScript transformer, compute total licensed images per month, and display as a Chart component.

To check if a specific image is downloadable with your current license agreement, call GET /images/{{ imageId }}/downloadauthorizations. This returns the available product agreements that cover this image and confirms whether your account has download access before the user attempts a download.

For procurement teams managing large Getty Images budgets across multiple departments, building automated license expiration alerts and budget tracking tied to download volume, RapidDev's team can help build the complete compliance monitoring Retool solution.

```
// Transformer: group downloads by month for Chart
const downloads = getDownloads.data || [];
const monthly = {};

downloads.forEach(dl => {
  const date = new Date(dl.downloaded_at);
  const key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
  monthly[key] = (monthly[key] || 0) + 1;
});

const sortedKeys = Object.keys(monthly).sort();
return {
  x: sortedKeys,
  y: sortedKeys.map(k => monthly[k]),
  total_downloads: downloads.length,
  total_months: sortedKeys.length,
  avg_per_month: sortedKeys.length > 0
    ? (downloads.length / sortedKeys.length).toFixed(1)
    : 0
};
```

**Expected result:** The image detail panel shows a watermarked comp preview, full metadata, and download authorization status. The compliance Chart shows monthly download volume for license budget tracking.

## Best practices

- Implement automatic token refresh as a Retool Workflow on a 25-minute schedule — Getty Images tokens expire after 30 minutes and manually refreshing them during active dashboard use is disruptive.
- Never store Getty Images display URI values (thumbnail URLs) persistently — they contain embedded authentication tokens that expire. Store only asset IDs and re-fetch display URIs when needed.
- Always check download authorization (GET /images/{id}/downloadauthorizations) before presenting a download button to users — downloading without authorization can trigger unintended billing charges.
- Use the fields parameter in all search queries to request only the data you need — requesting display_sizes and download_sizes returns significantly more data than id and title alone, slowing large searches.
- Store Getty Images asset IDs alongside project and requester information in your own database when tracking licensed image usage — this enables compliance reporting that Getty's native download history view doesn't support.
- Use editorial asset_family filter for news/journalism use cases and creative for marketing campaigns — mixing them returns results licensed under different terms, which can cause compliance issues.
- Watermarked comp images are for layout and approval only — never use them as final published content. Always show a reminder in your Retool UI that comp images require formal licensing before publication.
- Cache search results for 2 minutes when users are paginating through the same search — this prevents redundant API calls when navigating between result pages of the same query.

## Use cases

### Build an editorial image search and approval dashboard

Create a Retool panel where editors can search Getty's editorial image library with filters for event, date range, photographer, and orientation. Search results display image thumbnails, captions, and photographer credits. Editors can add approved images to a board for team review and final download authorization.

Prompt example:

```
Build a Retool editorial image search panel. Add a search input, date range picker, and orientation select (horizontal/vertical/square). Fetch results from Getty Images API and display as a grid showing thumbnail, photographer name, caption, and collection type. Add an 'Add to Board' button that saves selected images to a designated Getty board. Show total result count and image ID for licensing reference.
```

### Build a license compliance and usage tracking dashboard

Build a Retool tool that tracks all images downloaded from Getty Images by team members, shows license type and expiration dates, and flags potentially expired or misused images. Media managers can see which departments are the heaviest Getty users and ensure all downloaded images have appropriate licenses for their use case.

Prompt example:

```
Build a Retool Getty Images license tracking dashboard. Show all recent downloads with: image ID, title, download date, user who downloaded, license type, and expiration date. Color-code rows: red for expired licenses, yellow for expiring within 30 days, green for valid. Add filters by department and date range. Show a summary bar chart of downloads by department this month.
```

### Build a project media board management tool

Create a Retool panel for managing Getty Images boards (curated collections) across multiple campaigns or projects. Marketing teams can create boards for upcoming campaigns, add approved images to boards, share board URLs with stakeholders, and track which board images have been formally licensed for production use.

Prompt example:

```
Build a Retool media board management panel. List all Getty Images boards with: board name, image count, created date, and owner. Clicking a board shows all images in it with thumbnails, asset IDs, and license status. Add Create Board, Delete Board, and Add Images to Board actions. Show an Export List button that generates a CSV of all board images with their asset IDs for procurement reference.
```

## Troubleshooting

### 401 Unauthorized on all API requests despite valid-looking credentials

Cause: Getty Images OAuth 2.0 access tokens expire after 1800 seconds (30 minutes). A token that was valid when you configured the resource may have expired by the time you run queries.

Solution: Re-run the token acquisition request: POST https://authentication.gettyimages.com/oauth2/token with grant_type=client_credentials, client_id, and client_secret. Update the GETTY_ACCESS_TOKEN configuration variable in Retool Settings → Configuration Variables with the fresh token. Implement a Retool Workflow that refreshes the token on a 25-minute schedule to prevent expiration during active use.

```
// Token refresh request (form-encoded body):
// POST https://authentication.gettyimages.com/oauth2/token
// Content-Type: application/x-www-form-urlencoded
// Body: grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET
```

### Image thumbnails display as broken images in the Table

Cause: Getty Images display_size URIs include time-limited authentication tokens embedded in the URL. If the token was embedded when the query ran and significant time has passed, the thumbnail URLs may expire.

Solution: Re-run the search query to get fresh display_size URIs. For persistent image storage in boards or download history, always store the asset_id and re-fetch display URIs on demand rather than storing the URI itself. Add a Refresh button on the detail view that re-fetches current thumbnail URIs for selected images.

### Search returns 403 Forbidden when filtering by specific editorial segments or requesting download URIs

Cause: Your Getty Images API application may have access restrictions based on your licensing tier. Some editorial segments, download endpoints, and commercial use cases require specific license agreements beyond basic API access.

Solution: Review your Getty Images API application permissions in the developer portal. Contact your Getty Images account manager to clarify which API endpoints are included in your licensing agreement. The /images/search endpoint for basic display is available to all API users; download access (/downloads) and commercial content access require additional agreements.

### Board operations (create, add image) return 404 Not Found

Cause: Board management endpoints require the correct board ID format. Also, boards are user-account specific — if the access token is for a different user account than the boards were created under, they will not be accessible.

Solution: Confirm board IDs by first running GET /boards and using the exact id values returned. Verify that the OAuth token is for the account that owns the boards. Board IDs in Getty Images are string identifiers, not integers — ensure they are passed as strings in URL paths.

```
// Correct board endpoint format:
// GET /boards/{boardId}/assets
// Where boardId is the string ID from GET /boards response
// NOT an integer or a board name
```

## Frequently asked questions

### Does Retool have a native Getty Images connector?

No, Retool does not have a dedicated native connector for Getty Images. You connect via a REST API Resource using Getty Images OAuth 2.0 client credentials authentication. The setup takes about 25 minutes and provides access to image search, display thumbnails, board management, download history, and download authorization endpoints.

### Do I need a paid Getty Images subscription to use their API?

Basic API access for image search and display is available with a developer account at no cost. However, downloading and licensing images for publication requires a Getty Images commercial subscription or on-demand purchase agreement. Contact Getty Images directly to establish a licensing agreement that fits your organization's image usage volume.

### How do I display Getty Images thumbnails in Retool without violating license terms?

Getty Images allows display of thumbnail and watermarked preview images (the 'thumb' and 'comp' sizes from the display_sizes field) for internal review and selection purposes without a separate license. These images are watermarked. For final publication, you must download the unlicensed high-resolution version through your commercial agreement. In Retool, use Table or Gallery components to show thumb URIs for selection workflows, and clearly label comp images as 'Preview Only - Requires License'.

### How often do Getty Images API access tokens expire?

Getty Images OAuth 2.0 access tokens expire after 1800 seconds (30 minutes). You must refresh them by re-requesting a token using the client credentials flow. For ongoing Retool dashboards, implement a Retool Workflow on a 25-minute schedule that automatically requests a fresh token and updates the GETTY_ACCESS_TOKEN configuration variable. This prevents interruptions during active dashboard sessions.

### Can I use the Getty Images API for automated image selection without human review?

Technically yes, the API allows programmatic search and selection. However, Getty Images' terms of service require that editorial images are used accurately and in proper context. For compliance, retain human editorial review in the workflow rather than fully automating image selection for published content. Build your Retool tool to present options to editors rather than auto-publishing selected images.

---

Source: https://www.rapidevelopers.com/retool-integrations/getty-images-api
© RapidDev — https://www.rapidevelopers.com/retool-integrations/getty-images-api