trawl-sdk 0.1.4

Python SDK for the Trawl unified content API

Trawl Python SDK

The official Python SDK for the Trawl API — extract transcripts from YouTube, podcasts, TikTok, earnings calls, SEC filings, news, and academic papers.

Install

pip install trawl

Quick Start

from trawl import TrawlClient

client = TrawlClient(api_key="trawl_your_key")

# Search YouTube
results = client.search.youtube("machine learning tutorial", max_results=5)
for video in results.results:
    print(f"{video.title} — {video.channel}")

# Extract a transcript
transcript = client.transcripts.extract("https://youtube.com/watch?v=dQw4w9WgXcQ")
print(f"{len(transcript.segments)} segments extracted")

# Preview without auth (free)
preview = client.transcripts.preview("https://youtube.com/watch?v=dQw4w9WgXcQ")

# Bulk download as ZIP
zip_bytes = client.bulk.download(["dQw4w9WgXcQ", "9bZkp7q19f0"], format="jsonl")

All Resources

client = TrawlClient(api_key="trawl_your_key")

# YouTube
client.search.youtube(query, max_results=10)
client.transcripts.extract(url, language=None)
client.transcripts.preview(url)              # No auth needed
client.transcripts.download(id, format="txt")
client.bulk.download(video_ids, format="txt") # No auth needed

# Podcasts
client.search.podcasts(query, max_results=20)
client.podcasts.episodes(podcast_id)
client.podcasts.transcribe(audio_url)

# Earnings Calls
client.earnings.search("AAPL")
client.earnings.get_transcript("AAPL", 2026, 1)
client.earnings.get_chunks("AAPL", 2026, 1)

# SEC Filings
client.filings.search("AAPL", form_type="10-K")

# News (GDELT)
client.news.search("Federal Reserve", language="en")
client.news.get_article_text("https://example.com/article")

# Academic Papers
client.papers.search("transformer architecture")
client.papers.extract(arxiv_id="2301.08745")

# AI Analysis
client.ai.summarize(transcript_id)
client.ai.topics(transcript_id)
client.ai.entities(transcript_id)
client.ai.preview_summarize("Raw text to summarize")  # No auth

# Jobs
client.jobs.get(job_id)
client.jobs.list()

Error Handling

from trawl.exceptions import (
    TrawlError,
    AuthenticationError,  # 401
    NotFoundError,        # 404
    RateLimitError,       # 429
    ValidationError,      # 422
)

try:
    transcript = client.transcripts.extract("invalid-url")
except ValidationError as e:
    print(f"Bad request: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")

Context Manager

with TrawlClient(api_key="trawl_your_key") as client:
    results = client.search.youtube("python")
    # client.close() called automatically

Requirements

• Python 3.10+
• httpx

Links

• API Documentation
• RAG Pipeline Tutorial
• GitHub