Artlist APIartlist.io ↗
Search and browse Artlist.io stock footage clips. Get metadata on resolution, duration, filmmaker, formats, and thumbnails via a single API endpoint.
What is the Artlist API?
The Artlist.io API provides access to Artlist's stock footage catalog through one endpoint, search_stock_footage, returning up to 24 clips per page with over a dozen metadata fields per clip — including resolution, duration, orientation, filmmaker info, thumbnail URL, and preview URL. You can search by keyword, filter by category, sort results, and optionally include or exclude AI-generated content.
curl -X GET 'https://api.parse.bot/scraper/5d068888-4b41-4074-af53-4793ac16115a/search_stock_footage?sort=staff_picks&query=nature&category=nature_landscapes' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace artlist-io-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Artlist stock footage search — bounded, re-runnable."""
from parse_apis.artlist_io_api import Artlist, Sort, InputFormatInvalid
client = Artlist()
# Browse staff-picked footage, capped at 5 clips total.
for clip in client.clips.search(sort=Sort.STAFF_PICKS, limit=5):
print(clip.name, f"{clip.width}x{clip.height}", f"{clip.duration_ms}ms")
# Search for nature clips, grab the first result and inspect its formats.
clip = client.clips.search(query="nature", sort=Sort.NEWEST, limit=1).first()
if clip is not None:
print(clip.name, clip.filmmaker_name, clip.orientation)
for fmt in clip.available_formats:
print(f" format: {fmt.display_name}")
# Filter by category, excluding AI-generated content.
try:
for clip in client.clips.search(query="ocean", category="nature_landscapes", include_ai=False, limit=3):
print(clip.name, "ai:" if clip.is_made_with_ai else "original:", clip.result_type)
except InputFormatInvalid as e:
# Raised when a parameter value is rejected by the upstream API.
print(f"Invalid input: {e.message}")
print("exercised: clips.search (browse / keyword / category filter)")
Search stock footage clips by keyword with optional category filtering and sort order. Returns paginated results (approximately 24 clips per page) with metadata including resolution, duration, filmmaker, and available formats. When no query is provided, returns browse results in the selected sort order. The total_exact field indicates total matching clips available for pagination.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination, starting at 1. |
| sort | string | Sort order for results. |
| query | string | Search keywords (e.g. 'nature', 'ocean waves', 'city'). When omitted, returns browse results. |
| category | string | Comma-separated category keys or numeric IDs to filter results. Category keys include video themes (e.g. 'nature_landscapes', 'business', 'travel', 'urban'), shot types (e.g. 'close_up', 'aerial', 'macro'), and people filters (e.g. 'no_people', 'male', 'female'). Multiple categories can be combined with commas. |
| include_ai | boolean | Whether to include AI-generated content in results. |
{
"type": "object",
"fields": {
"page": "current page number",
"sort": "sort order used",
"clips": "array of stock footage clip objects with id, name, thumbnail_url, preview_url, filmmaker info, duration, resolution, orientation, and available formats",
"total_exact": "total number of exact match results available",
"total_similar": "total number of similar/related results"
},
"sample": {
"data": {
"page": 1,
"sort": "staff_picks",
"clips": [
{
"id": 19960,
"name": "branches with green leaves in bright day",
"width": 4608,
"height": 2160,
"is_new": false,
"is_vfx": false,
"story_id": 10927,
"story_name": "Blooming Season",
"duration_ms": 5560,
"is_original": true,
"orientation": "HORIZONTAL",
"preview_url": "https://cms-public-artifacts.artlist.io/content/artgrid/footage-hls/815433bd-9011-41a8-a4a3-a9c799ceae70_playlist_1755521081.m3u8",
"result_type": "exact",
"filmmaker_id": 322,
"name_for_url": "branches-with-green-leaves-in-bright-day",
"thumbnail_url": "https://artgrid.imgix.net/footage-graded-thumbnail/815433bd-9011-41a8-a4a3-a9c799ceae70_gradedThumbnail_w800px_e7e37ef2-c0bc-4574-85e3-e6be2db6f1e5_1755521019748.jpeg",
"filmmaker_name": "Ami Bornstein",
"is_made_with_ai": false,
"available_formats": [
{
"id": "hd_preview",
"displayName": "HD Preview"
},
{
"id": "hd_graded",
"displayName": "HD"
},
{
"id": "hq_graded",
"displayName": "4.6K ProRes"
}
]
}
],
"total_exact": 116027,
"total_similar": 0
},
"status": "success"
}
}About the Artlist API
What the API Returns
The search_stock_footage endpoint returns paginated clip results from Artlist's stock footage library. Each response includes a clips array where every clip object carries fields such as id, name, thumbnail_url, preview_url, duration, resolution, orientation, and filmmaker details. The response also surfaces total_exact (the count of exact-match results) and total_similar (related results available beyond the exact matches), giving you visibility into full result set size for pagination planning.
Filtering and Sorting
The query parameter accepts natural-language keywords like 'ocean waves' or 'city timelapse'. Omitting query returns browse results rather than a keyword-matched set. The category parameter accepts comma-separated category keys or numeric IDs — covering video themes such as nature — and can be combined with query for narrower filtering. The sort parameter controls result ordering. The include_ai boolean flag lets you include or exclude AI-generated clips, which is relevant when you need to communicate source type to end users or filter for traditional footage only.
Pagination
Results are paginated at approximately 24 clips per page. The page parameter starts at 1. Use total_exact and total_similar from the response to calculate how many pages are available for a given query. Note that total_similar may surface additional clips beyond the exact match count, so iterating past the exact results can still yield relevant footage.
Source and Official API
Artlist.io does not publish a public developer API for stock footage search. This Parse API is the structured programmatic interface for accessing Artlist's footage catalog data.
The Artlist API is a managed, monitored endpoint for artlist.io — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when artlist.io changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official artlist.io API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a footage discovery tool that lets users keyword-search Artlist clips and preview thumbnails before licensing.
- Aggregate stock footage metadata across multiple libraries, comparing resolution and duration fields from Artlist alongside other sources.
- Filter footage by category and AI-generation status to curate collections for specific production requirements.
- Paginate through Artlist's catalog to index clip names, resolutions, and filmmaker credits for an internal asset database.
- Surface filmmaker-attributed clips for editors who need to credit contributors in documentary or editorial projects.
- Build a content recommendation feed that browses Artlist footage by category without requiring a keyword search.
- Track availability and variety of vertical-orientation clips by filtering orientation field for short-form video production workflows.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Artlist.io have an official developer API?+
What does each clip object in the response include?+
clips array includes fields for id, name, thumbnail_url, preview_url, duration, resolution, orientation, filmmaker info, and available formats. The total_exact and total_similar fields at the response level indicate how many results exist for pagination.How does pagination work and what do `total_exact` and `total_similar` mean?+
page parameter starts at 1 and each page returns approximately 24 clips. total_exact reflects the count of clips that directly match your query, while total_similar reflects related results that may appear beyond the exact matches. Use both figures to decide how many pages to fetch for complete coverage of a search.Does the API return licensing details or download URLs for clips?+
thumbnail_url, preview_url, resolution, duration, and format availability, but does not expose licensing terms or full-resolution download URLs. You can fork this API on Parse and revise it to add an endpoint targeting individual clip detail pages where licensing information may be available.Can I retrieve clips by a specific filmmaker or filter by duration range?+
query, category, sort, and include_ai. You can fork this API on Parse and revise it to add filmmaker-specific or duration-range filtering as additional parameters.