Unsplash Image Search Scraper

Search public Unsplash photos by keyword and save one normalized, source-attributed record per photo. Use it for visual research, content planning, and asset catalogs when you need public photo-page URLs, delivery URLs, photographer attribution, dimensions, tags, source query, and collection time.

Choose this Actor when

• You have one to ten descriptive image-search phrases, such as minimal home office or mountain lake.
• You need structured metadata for each result rather than manually browsing a results page.
• You need provenance fields (photoUrl, sourceUrl, scrapedAt) and a clear Unsplash licensing reference alongside every record.

Do not use it to download image files, to obtain rights to an image, or to fetch a known photo by URL or ID. It searches public Unsplash result pages and returns metadata and image delivery URLs; review the Unsplash License before using any image.

What one result means

Each dataset row represents one unique public Unsplash photo found for a submitted query. The Actor deduplicates photo IDs across all queries in the run and records the query that produced the item.

Field	Meaning
photoUrl	Canonical public Unsplash photo page.
imageUrlRegular	Image delivery URL suitable for a regular-size preview when provided by Unsplash.
photographerName / photographerProfileUrl	Public attribution supplied by Unsplash.
width / height	Source dimensions in pixels when available.
tags	Public Unsplash tags, if supplied.
sourceUrl / scrapedAt	Requested search page and ISO-8601 collection time.
license / licenseUrl	Source licensing context, not a grant of rights from this Actor.

Here is a real normalized record from a canary search on 2026-07-15 (some nullable fields omitted only for readability):

{
    "id": "7VotVatHM7Q",
    "title": "a lake surrounded by trees with mountains in the background",
    "photoUrl": "https://unsplash.com/photos/a-lake-surrounded-by-trees-with-mountains-in-the-background-7VotVatHM7Q",
    "imageUrlRegular": "https://plus.unsplash.com/premium_photo-1673240367277-e1d394465b56?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3wxMjA3fDB8MXxzZWFyY2h8MXx8bW91bnRhaW4lMjBsYWtlfGVufDB8fHx8MTc4NDEzODY0N3ww&ixlib=rb-4.1.0&q=80&w=1080",
    "width": 4240,
    "height": 2832,
    "photographerName": "Davey Gravy",
    "photographerProfileUrl": "https://unsplash.com/@davey_gravy",
    "query": "mountain lake",
    "rank": 1,
    "sourceUrl": "https://unsplash.com/s/photos/mountain%20lake?orientation=landscape&color=blue",
    "scrapedAt": "2026-07-15T18:04:07.739Z",
    "license": "Unsplash License",
    "licenseUrl": "https://unsplash.com/license"
}

Quick start

The default run searches mountains, saves up to 10 results for that query, and never saves more than 20 rows in total. Use a smaller cap for the lowest-cost test.

{
    "queries": ["mountain lake", "minimal home office"],
    "maxItemsPerQuery": 5,
    "maxTotalItems": 8,
    "orientation": "landscape",
    "color": "blue",
    "orderBy": "relevant"
}

The Actor accepts plain-language search phrases only. orientation, color, and orderBy filter Unsplash's result feed; they do not alter image pixels or re-sort the saved dataset.

API example

curl -sS -X POST \
  "https://api.apify.com/v2/acts/khadinakbar~unsplash-image-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["mountain lake"],
    "maxItemsPerQuery": 3,
    "maxTotalItems": 3,
    "orientation": "landscape",
    "color": "blue",
    "orderBy": "relevant"
  }'

When the run finishes, read its default dataset from the run response's defaultDatasetId, or open the Images view in the Console.

Pricing and cost cap

This Actor uses Pay per event + usage:

• apify-actor-start: $0.00005 once per valid run.
• image-found: $0.003 for each complete, validated image record the Actor charges immediately before persisting it to the default dataset.
• Apify platform usage (browser compute and residential proxy usage) is additional and reported separately by Apify.

For example, saving 8 rows costs $0.00005 + (8 × $0.003) = $0.02405 in event charges, plus platform usage. Before collection begins, the Actor displays the event-charge ceiling implied by your result cap. It stops saving rows when either maxTotalItems or the Apify event-charge limit is reached. Invalid and duplicate candidates are never charged. If Apify storage fails after a charge is accepted, the run is marked PARTIAL with an explicit reconciliation warning.

A practical workflow

A content strategist preparing a brand mood board searches warm cafe interior and handmade ceramics, then exports the dataset to a spreadsheet. photographerName, photoUrl, and licenseUrl keep the candidate list attributable, while width, height, and color make it easy to filter options before the team reviews the original Unsplash pages. The Actor is read-only: it does not modify Unsplash or download assets.

If the team starts with a reference website rather than search terms, use the public Website Content Crawler first to extract its brand language, then pass the resulting themes here as queries for image discovery.

For AI agents and MCP clients

Search Unsplash for up to 10 landscape photos matching "mountain lake". Return each photo's title, regular image URL, photographer, dimensions, source page, and collection timestamp. Stop at 10, preserve source attribution, and report whether the run was complete, partial, or empty.

Give the Actor queries as an array of ordinary descriptive phrases. Read the default dataset for records and OUTPUT / RUN_SUMMARY in the default key-value store for the terminal outcome. The Actor exposes COMPLETE, PARTIAL, VALID_EMPTY, INVALID_INPUT, UPSTREAM_FAILED, or CONFIG_ERROR; only complete, validated rows are billable image events.

Limits and recovery

Outcome or symptom	Meaning	Next step
VALID_EMPTY	The query and filters were valid but produced no matching photos.	Broaden the phrase or remove a filter.
INVALID_INPUT	A query was blank or a result limit was outside the documented range.	Use the Quick start input shape and retry.
PARTIAL	Some useful records were saved, but a query or write failed.	Keep the saved rows; inspect RUN_SUMMARY.warnings and retry only the affected search.
UPSTREAM_FAILED	The browser could not complete a usable public Unsplash search.	Retry later with a smaller input; no image rows are invented after a failure.

Unsplash can change its public site, available fields, filters, delivery URLs, and anti-bot behavior without notice. The DOM fallback intentionally returns only verified public fields and uses explicit null values where rich metadata is unavailable.

Verification evidence and legal boundary

The previous deployed Chrome build 0.1.3 was canary-tested on 2026-07-15 with a mountain lake query and returned 3 complete rich records. The current release is verified again after deployment; target-site content and availability remain independently variable.

Use this Actor only with public or otherwise authorized data, in compliance with applicable law, the Unsplash Terms, the Unsplash License, and your own privacy and intellectual-property obligations. Metadata and URLs are not a license grant, legal advice, or a substitute for checking the original source page.