Unsplash API: Search photos
Finds Unsplash photos matching a search phrase, in search order, optionally by shape; excludes Unsplash+ photos unless included. Each result has image links, photographer, licence and photo page.
Unofficial. Not affiliated with or endorsed by Unsplash.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Page optional
page Page of results for the requested count, for example 1.
2
Whole number 1 or more. Default
1.- Query, required
query What the photos should show, for example team meeting.
mountain lake
- Max Results optional
max_results Maximum photos per returned page, for example 20.
25
Whole number from 1 to 100. Default
20.- Orientation optional
orientation Photo shape to show, for example landscape.
square
One of
any,landscape,portrait,square. Defaultany.- Include Unsplash Plus optional
include_unsplash_plus Include paid Unsplash+ photos, for example false.
false (default)
True or false.
Input as JSON
{ "page": 2, "query": "mountain lake", "max_results": 25, "orientation": "square"}Output
{ "photos": [ { "likes": 1, "width": 3512, "height": 3512, "photo_id": "WW1vKFl-1A0", "blur_hash": "LbGvbNo~M_j?~VVsaxoL-=R-W=jY", "description": "a lake surrounded by mountains", "licence_note": "Free to use under the Unsplash License", "photo_page_link": "https://unsplash.com/photos/a-lake-surrounded-by-mountains-WW1vKFl-1A0" , "is_unsplash_plus": false, "photographer_name": "Geoffrey Chevtchenko", "regular_image_link": "https://images.unsplash.com/photo-1660405821949-d77300248265?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8MjZ8fG1vdW50YWluJTIwbGFrZXxlbnwwfDJ8fHwxNzkwNjQzMzQ5fDI&ixlib=rb-4.1.0&q=80&w=1080" , "full_size_image_link": "https://images.unsplash.com/photo-1660405821949-d77300248265?crop=entropy&cs=srgb&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8MjZ8fG1vdW50YWluJTIwbGFrZXxlbnwwfDJ8fHwxNzkwNjQzMzQ5fDI&ixlib=rb-4.1.0&q=85" , "photographer_profile_link": "https://unsplash.com/@geoffreychevt" }, { "likes": 2, "width": 4160, "height": 4160, "photo_id": "jIhzqVGz6cU", "blur_hash": "LfFsJTDhaej]_4M_odae-=NGs8j[", "description": "a body of water surrounded by mountains", "licence_note": "Free to use under the Unsplash License", "photo_page_link": "https://unsplash.com/photos/a-body-of-water-surrounded-by-mountains-jIhzqVGz6cU" , "is_unsplash_plus": false, "photographer_name": "Geoffrey Chevtchenko", "regular_image_link": "https://images.unsplash.com/photo-1660406111704-176de8d85b0f?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8Mjd8fG1vdW50YWluJTIwbGFrZXxlbnwwfDJ8fHwxNzkwNjQzMzQ5fDI&ixlib=rb-4.1.0&q=80&w=1080" , "full_size_image_link": "https://images.unsplash.com/photo-1660406111704-176de8d85b0f?crop=entropy&cs=srgb&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8Mjd8fG1vdW50YWluJTIwbGFrZXxlbnwwfDJ8fHwxNzkwNjQzMzQ5fDI&ixlib=rb-4.1.0&q=85" , "photographer_profile_link": "https://unsplash.com/@geoffreychevt" }, { "likes": 0, "width": 3512, "height": 3512, "photo_id": "HtDjgGliwaQ", "blur_hash": "LQDT;Ek=s+bc@qV@t7jbk;RjV?oz", "description": "a rocky beach with a body of water in the front", "licence_note": "Free to use under the Unsplash License", "photo_page_link": "https://unsplash.com/photos/a-rocky-beach-with-a-body-of-water-in-the-front-HtDjgGliwaQ" , "is_unsplash_plus": false, "photographer_name": "Geoffrey Chevtchenko", "regular_image_link": "https://images.unsplash.com/photo-1660406058489-08b7932fcc68?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8Mjh8fG1vdW50YWluJTIwbGFrZXxlbnwwfDJ8fHwxNzkwNjQzMzQ5fDI&ixlib=rb-4.1.0&q=80&w=1080" , "full_size_image_link": "https://images.unsplash.com/photo-1660406058489-08b7932fcc68?crop=entropy&cs=srgb&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8Mjh8fG1vdW50YWluJTIwbGFrZXxlbnwwfDJ8fHwxNzkwNjQzMzQ5fDI&ixlib=rb-4.1.0&q=85" , "photographer_profile_link": "https://unsplash.com/@geoffreychevt" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"unsplash.com/search_photos","input":{"page":2,"query":"mountain lake","max_results":25,"orientation":"square"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "unsplash.com/search_photos" , "input": { "page": 2, "query": "mountain lake", "max_results": 25, "orientation": "square" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "unsplash.com/search_photos" , "input": { "page": 2, "query": "mountain lake", "max_results": 25, "orientation": "square" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run unsplash.com/search_photos# with {"page":2,"query":"mountain lake","max_results":25,"orientation":"square"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "query" ], "properties": { "page": { "type": "integer", "default": 1, "minimum": 1, "description": "Page of results for the requested count, for example 1." }, "query": { "type": "string", "minLength": 1, "description": "What the photos should show, for example team meeting." }, "max_results": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1, "description": "Maximum photos per returned page, for example 20." }, "orientation": { "enum": [ "any", "landscape", "portrait", "square" ], "type": "string", "default": "any", "description": "Photo shape to show, for example landscape." }, "include_unsplash_plus": { "type": "boolean", "default": false, "description": "Include paid Unsplash+ photos, for example false." } }}Output schema
{ "type": "object", "required": [ "photos" ], "properties": { "photos": { "type": "array", "items": { "type": "object", "required": [ "description", "photographer_name", "photographer_profile_link", "regular_image_link", "full_size_image_link", "width", "height", "likes", "is_unsplash_plus", "licence_note", "photo_page_link", "photo_id", "blur_hash" ], "properties": { "likes": { "type": [ "integer", "null" ], "description": "Number of likes." }, "width": { "type": [ "integer", "null" ], "description": "Image width in pixels." }, "height": { "type": [ "integer", "null" ], "description": "Image height in pixels." }, "photo_id": { "type": "string", "description": "Unsplash photo ID." }, "blur_hash": { "type": [ "string", "null" ], "description": "Blur hash for a preview." }, "description": { "type": [ "string", "null" ], "description": "Photo description, or null if not available." }, "licence_note": { "type": "string", "description": "Licence requirement for this photo." }, "photo_page_link": { "type": "string", "description": "Photo page on Unsplash." }, "is_unsplash_plus": { "type": "boolean", "description": "Whether the image requires an Unsplash+ licence." }, "photographer_name": { "type": [ "string", "null" ], "description": "Photographer name." }, "regular_image_link": { "type": [ "string", "null" ], "description": "Image around 1080 pixels wide." }, "full_size_image_link": { "type": [ "string", "null" ], "description": "Full-size image." }, "photographer_profile_link": { "type": [ "string", "null" ], "description": "Photographer profile page." } } } } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
unsplash.com/search_photos- Returns
- description, photographer, image links, size, likes, Unsplash+ flag, licence note, photo page link, photo ID, blur hash
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method unsplash.com/search_photos with the inputs above.
Ask your agent
- Find me 10 landscape-oriented free photos of misty pine forests at dawn that I can use as a website hero banner, with photographer credits.
- I need portrait-shaped stock images of a barista pouring latte art — give me the image links, who shot them, and the license info.
- Search Unsplash for square photos of 'golden retriever puppy', include the Unsplash+ premium ones too, and show page 2 of results.
- Pull up around 30 photos of people collaborating in a modern office for a pitch deck; any orientation is fine, but only free ones.
- What are the top results on unsplash.com for 'Tokyo street at night neon'? I want image URLs, like counts, and blur hashes for lazy-loading placeholders.
See more
Search free stock photos on Pexels by subject, orientation, and page. Returns up to 80 photos in search order; Pexels may broaden searches with few exact matches.
pexels.com/search_photosFinds free stock videos on Pexels by search words, with creator, duration, preview image and a direct MP4 link, in Pexels search order starting at the chosen results page.
pexels.com/search_videosFinds free-to-use Wikimedia Commons images for a topic in Commons relevance order. Each image comes with its links, creator and licence details.
commons.wikimedia.org/search_free_imagesFinds Pinterest pins for an idea in search order, with image, creator, board, saves and linked website. Limited to the first public search page.
pinterest.com/search_pinsFinds Chrome Web Store extensions by keywords in store order, with each listing's developer, users, rating, rating count, short description and store link. Some listings omit developer, users or ratings.
chromewebstore.google.com/search_extensionsSearches public Bluesky posts for words, optionally ordered by latest or top and filtered by date, author or language. Search indexing may lag behind new posts.
bsky.app/search_postsSearches Bing and returns web results in the order shown, with snippets, answer-box text when available, and related searches.
bing.com/search_webFinds Product Hunt products by name or by what they do, in Product Hunt search order, with tagline, review rating, review count, followers and topics. Ratings are null for products without reviews.
producthunt.com/search_products
