Getyarn APIgetyarn.io ↗
Search getyarn.io video clips by subtitle phrase. Returns clip ID, source title, quote text, direct mp4 URL, and duration for up to 20 results per page.
What is the Getyarn API?
The getyarn.io API exposes a single search_clips endpoint that queries the site's library of TV and movie subtitle clips and returns up to 20 clip records per page, each containing 8 fields including the source title, verbatim quote text, a direct mp4 URL, a subtitled mp4 variant, a thumbnail, and a clip page URL. You can filter results by genre, content rating, decade, and media type before making a request.
curl -X GET 'https://api.parse.bot/scraper/2c0d0691-3a6c-49fa-8829-05d1758c2144/search_clips?query=you+shall+not+pass' \ -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 getyarn-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: Yarn clip search — find movie/TV quotes, filter by media type."""
from parse_apis.getyarn_io_api import Yarn, MediaType, InputFormatInvalid
client = Yarn()
# Search for a famous quote across all media, capped at 5 results.
for clip in client.clips.search(query="you shall not pass", limit=5):
print(clip.quote, "-", clip.source_title, f"({clip.duration_seconds}s)")
# Narrow to movies only and grab the top hit; handle invalid-input errors.
try:
top_movie_clip = client.clips.search(
query="here's looking at you",
media_type=MediaType.MOVIES,
limit=1,
).first()
except InputFormatInvalid as e:
print("Bad request:", e.message)
top_movie_clip = None
if top_movie_clip is not None:
print(top_movie_clip.quote)
print("source:", top_movie_clip.source_title)
print("watch:", top_movie_clip.mp4_url)
print("score:", top_movie_clip.score)
print("exercised: clips.search (all media) / clips.search (movies filter) / InputFormatInvalid")
Searches video clips whose subtitles match a word or phrase and returns one page of 20 clip records ranked by relevance (the site uses fuzzy matching, so lower-ranked results may only partially match). Each record carries the source show or movie title (the site's only title for a clip, e.g. a show name with season/episode), the quoted subtitle text, the clip page URL, the direct mp4 URL, a subtitled mp4 variant, thumbnail/GIF URLs, the clip duration in seconds and its start/end offsets in the source video. Pagination is page-numbered: page defaults to 1, and has_more tells whether a further page exists; total_hits is the site's own hit count, which it caps at 100000. Optional filters narrow by media type, genre, decade and content rating; an unrecognized filter value is passed to the site and typically yields the site's fallback (fewer or fuzzier) results rather than an error. One site request per call.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page; each page holds 20 clips. |
| genre | string | Genre label filter as shown in the site's genre facet (e.g. Fantasy, Comedy, Drama). Omitted = all genres. |
| queryrequired | string | Word or phrase to search for in clip subtitles. |
| rated | string | Content-rating filter as shown in the site's rating facet (e.g. TV-PG, PG-13, R). Omitted = all ratings. |
| decade | string | Decade filter as a 4-digit decade start year as shown in the site's decade facet (e.g. 1960, 2010). Omitted = all decades. |
| media_type | string | Restrict results to one media category. Omitted = all media. |
{
"type": "object",
"fields": {
"page": "integer, the 1-based page returned",
"clips": "array of clip records: clip_id, source_title (show/movie title), quote (subtitle text), clip_url, mp4_url, subtitled_mp4_url, thumbnail_url, gif_url, duration_seconds (number), start_time_seconds, end_time_seconds, content_type (episode/movie or null), source_id (show/movie id), score (relevance)",
"query": "echo of the searched phrase",
"has_more": "boolean, whether a next page exists",
"page_size": "integer, clips per page (20)",
"total_hits": "integer, site-reported matching clip count (capped at 100000)"
},
"sample": {
"data": {
"page": 1,
"clips": [
{
"quote": "You shall not pass!",
"score": 240.69667,
"clip_id": "fa41b589-210d-4149-bd11-f2d19e640c14",
"gif_url": "https://y.yarn.co/fa41b589-210d-4149-bd11-f2d19e640c14_text.gif",
"mp4_url": "https://y.yarn.co/fa41b589-210d-4149-bd11-f2d19e640c14.mp4",
"clip_url": "https://getyarn.io/yarn-clip/fa41b589-210d-4149-bd11-f2d19e640c14",
"source_id": "066d4f03-1b02-4de2-b78f-5d28d5fdb8e5",
"content_type": "episode",
"source_title": "Miraculous: Tales of Ladybug & Cat Noir (2015) - S02E12 Gorizilla",
"thumbnail_url": "https://y.yarn.co/fa41b589-210d-4149-bd11-f2d19e640c14_thumb.jpg",
"duration_seconds": 2.9,
"end_time_seconds": 916.54,
"subtitled_mp4_url": "https://y.yarn.co/fa41b589-210d-4149-bd11-f2d19e640c14_text.mp4",
"start_time_seconds": 913.66
}
],
"query": "you shall not pass",
"has_more": true,
"page_size": 20,
"total_hits": 100000
},
"status": "success"
}
}About the Getyarn API
What the API Returns
The search_clips endpoint accepts a query string and returns a paginated list of clips whose subtitle text matches that phrase. Each response includes clips, an array of records containing clip_id, source_title, quote, clip_url, mp4_url, subtitled_mp4_url, and thumbnail data. The response also echoes back your query, reports the current page, the fixed page_size of 20, a has_more boolean for pagination, and a total_hits count capped at 100,000.
Filtering and Pagination
Four optional filter parameters narrow the result set before it is returned. genre accepts labels like Fantasy, Comedy, or Drama. rated accepts standard content-rating strings such as TV-PG, PG-13, or R. decade takes a 4-digit decade start year (e.g. 1990, 2010). media_type restricts results to a single media category. All filters match the facet labels as displayed on the site. Pagination is 1-based via the page parameter; check has_more to determine whether additional pages exist.
Matching Behavior and Coverage
getyarn.io uses fuzzy matching, so results are ranked by relevance and lower-ranked clips on a given page may only partially match the queried phrase. The total_hits value reflects what the site reports and is capped at 100,000 regardless of actual library size. There is no endpoint for browsing by show title directly — discovery goes through subtitle text search.
The Getyarn API is a managed, monitored endpoint for getyarn.io — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when getyarn.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 getyarn.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 quote-search tool that retrieves the direct mp4_url for any memorable TV or movie line
- Generate reaction GIF or clip suggestions in a chat app by querying common phrases against the subtitle index
- Filter clips to a specific decade and genre to build a themed video-quote collection
- Correlate source_title frequency across a query set to find which shows produce the most clips for a given phrase
- Populate a content-rating-aware clip picker by filtering results with the rated parameter
- Embed subtitled video clips in educational tools using the subtitled_mp4_url field for accessibility
| 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.