API Documentation

import requests

response = requests.post(
    "https://api.gettrawl.com/api/transcripts/preview",
    json={"url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}
)
data = response.json()
for seg in data["segments"]:
    print(f"[{seg['start']:.1f}s] {seg['text']}")

from trawl import TrawlClient

# Use your API key
client = TrawlClient(api_key="trawl_your_key")

transcript = client.transcripts.extract("https://youtube.com/watch?v=dQw4w9WgXcQ")
print(f"Stored as ID {transcript.id} with {len(transcript.segments)} segments")

# Download
content = client.transcripts.download(transcript.id, format="srt")

from trawl import TrawlClient

client = TrawlClient(api_key="trawl_xxx")

# Search
results = client.search.youtube("machine learning", max_results=5)

# Extract
transcript = client.transcripts.extract("https://youtube.com/watch?v=...")

# Podcasts
podcasts = client.search.podcasts("Lex Fridman")
episodes = client.podcasts.episodes(podcasts.results[0].id)

# Bulk download as JSONL
zip_bytes = client.bulk.download(["vid1", "vid2"], format="jsonl")

from langchain_trawl import TrawlLoader

loader = TrawlLoader(
    urls=["https://youtube.com/watch?v=abc", "https://youtube.com/watch?v=def"],
    api_key="trawl_xxx",
)
docs = loader.load()
# docs[0].page_content = "Full transcript..."
# docs[0].metadata = {"video_id": "abc", "title": "...", "source": "..."}

client = TrawlClient(api_key="trawl_your_key")
transcript = client.transcripts.extract("https://youtube.com/watch?v=...")

results = client.search.youtube("AI tutorial", max_results=10)
for r in results.results:
    print(f"{r.title} — {r.channel}")

t = client.transcripts.extract("https://youtube.com/watch?v=abc123")
srt = client.transcripts.download(t.id, format="srt")

podcasts = client.search.podcasts("Lex Fridman")
episodes = client.podcasts.episodes(podcasts.results[0].id)
for ep in episodes:
    status = "✅ Free" if ep.has_transcript else "🎙️ AI Transcription"
    print(f"{status} {ep.title}")

job = client.podcasts.transcribe("https://example.com/ep.mp3")
print(f"Job {job.id}: {job.status}")

data = requests.post("https://api.gettrawl.com/api/tiktok/preview",
    json={"url": "https://tiktok.com/@user/video/7234567890123456789"}).json()

# Keyword search
results = client.tiktok_search.search("machine learning")

# User's videos
videos = client.tiktok_search.user_videos("username")

# Video comments
comments = client.tiktok_search.video_comments("7234567890123456789")

data = requests.post("https://api.gettrawl.com/api/instagram/preview",
    json={"url": "https://instagram.com/reel/ABC123/"}).json()

# Search
results = client.instagram_search.search("data science")

# User info
user = client.instagram_search.user_info("openai")

# User's reels
reels = client.instagram_search.user_reels(12345)

# Post comments
comments = client.instagram_search.post_comments("ABC123")

data = requests.post("https://api.gettrawl.com/api/twitter/preview",
    json={"url": "https://x.com/i/spaces/1eaKbrPAqbwKX"}).json()
for seg in data["segments"]:
    print(f"[{int(seg['start']//60):02d}:{int(seg['start']%60):02d}] {seg['text']}")

results = client.earnings.search("AAPL", from_date="2024-01-01", to_date="2025-01-01")
for call in results["results"]:
    print(f"{call['company_name']} Q{call['quarter']} {call['year']}")

transcript = client.earnings.get("AAPL", year=2024, quarter=4)
for section in transcript["sections"]:
    print(f"[{section['speaker']}] ({section['role']})")
    print(f"  {section['text'][:100]}...")

chunks = client.earnings.chunks("AAPL", year=2024, quarter=4)
for chunk in chunks:
    print(f"[chunk {chunk['chunk_index']}] {chunk['speaker']}: {chunk['text'][:80]}...")

results = client.filings.search("AAPL", form_type="10-K")
for filing in results["results"]:
    print(f"{filing['company_name']} {filing['form_type']} filed {filing['filed_date']}")

data = client.filings.form4("AAPL", date_after="2024-01-01")
for filing in data["filings"]:
    for owner in filing["owners"]:
        print(f"{owner['name']} ({owner['officer_title']})")
    for txn in filing["transactions"]:
        print(f"  {txn['transaction_type'].upper()}: {txn['shares']:,.0f} shares @ ${txn['price_per_share']}")

results = client.news.search("artificial intelligence")
for article in results["articles"]:
    print(f"[{article['source_domain']}] {article['title']}")

results = client.news.market_news(category="general")
for article in results["articles"]:
    print(f"[{article['source']}] {article['title']}")

results = client.news.company_news("AAPL")
for article in results["articles"]:
    print(f"[{article['source']}] {article['title']} ({article['published_date'][:10]})")

results = client.congress_trading.search(ticker="AAPL", from_date="2024-01-01")
for trade in results["trades"]:
    print(f"{trade['politician']} ({trade['chamber']}) — {trade['type']} ${trade['amount']}")

politicians = client.congress_trading.politicians(chamber="senate", min_trades=5)
for p in politicians:
    print(f"{p['name']} — {p['trade_count']} trades")

results = client.patents.search("machine learning", assignee="Google")
for patent in results["patents"]:
    print(f"{patent['patent_number']}: {patent['title']}")

patent = client.patents.get("US11526754B2")
print(f"Title: {patent['title']}")
print(f"Claims: {len(patent['claims'])}")

results = client.lobbying.search(client_name="Meta", issue_area="technology")
for filing in results["filings"]:
    print(f"{filing['registrant']} → {filing['client_name']}: ${filing['amount']}")

data = client.pageviews.get("Bitcoin", from_date="2024-01-01", to_date="2024-12-31", granularity="monthly")
for point in data["data"]:
    print(f"{point['date']}: {point['views']:,} views")

data = client.pageviews.compare(["Bitcoin", "Ethereum", "Solana"], from_date="2024-01-01")
for article, series in data["articles"].items():
    total = sum(p["views"] for p in series)
    print(f"{article}: {total:,} total views")

result = client.figi.lookup("AAPL", id_type="TICKER")
for instrument in result["data"]:
    print(f"{instrument['name']} — FIGI: {instrument['figi']}, Exchange: {instrument['exchCode']}")

pulse = client.pulse.get(geo="US", max_trends=5)
for item in pulse["pulse"]:
    print(f"[{item['alt_data_score']:.2f}] {item['trend']}")
    print(f"  Tickers: {', '.join(item['related_tickers'][:5])}")
    for signal in item["signals"]:
        print(f"  Signal: {signal['type']} ({signal['severity']})")

topic = client.pulse.topic("artificial intelligence chips")
for t in topic["tickers"]:
    print(f"{t['ticker']}: score {t['alt_data_score']:.2f}, {t['mention_count']} mentions")
    for s in t["signals"]:
        print(f"  {s['type']}: {s['description']}")

report = client.intelligence.get("AAPL", from_date="2024-01-01", sections="earnings,form4,congress")
print(f"Signals detected: {len(report['signals'])}")
for signal in report["signals"]:
    print(f"  [{signal['severity']}] {signal['description']}")

timeline = client.timeline.get("AAPL", from_date="2024-06-01", sources="form4,congress", limit=20)
for event in timeline["events"]:
    print(f"[{event['timestamp'][:10]}] {event['event_type']}: {event['title']}")

scan = client.scan.run(
    tickers=["AAPL", "MSFT", "NVDA"],
    from_date="2024-06-01",
    severity_filter="medium"
)
print(f"Signals found: {scan['signals_total']}")
for signal in scan["ranked_signals"]:
    print(f"  [{signal['severity']}] {signal['ticker']}: {signal['description']}")

anomalies = client.anomalies.get("AAPL", current_days=30, baseline_days=30)
print(f"Anomalies found: {anomalies['anomaly_count']}")
for a in anomalies["anomalies"]:
    if a["is_anomaly"]:
        print(f"  [{a['severity']}] {a['interpretation']}")

results = client.papers.search("transformer architecture")
for paper in results["results"]:
    print(f"[{paper['source']}] {paper['title']} ({paper['citation_count']} citations)")

extraction = client.papers.extract(arxiv_id="1706.03762")
print(f"Sections: {len(extraction['sections'])}")
for s in extraction["sections"]:
    print(f"  [{s['name']}] {len(s['text'])} chars")

results = client.reddit.search("machine learning", limit=5, from_date="2024-01-01", to_date="2025-01-01")
for post in results["posts"]:
    print(f"r/{post['subreddit']} | {post['title']} ({post['score']} pts)")

thread = client.reddit.get_thread("1abc123", sort="best")
print(f"Total segments: {thread['total_segments']}")
for seg in thread["segments"][:5]:
    print(f"  [{seg['metadata']['author']}] {seg['text'][:80]}")

mentions = client.reddit.mentions("NVDA", period="24h")
print(f"Mentions: {mentions['total_mentions']} in {mentions['period']}")
for sub in mentions["subreddits"]:
    print(f"  r/{sub['name']}: {sub['count']} mentions")

trending = client.reddit.trending(period="24h", limit=10)
for t in trending["tickers"]:
    print(f"{t['ticker']}: {t['mentions']} mentions, {t['sentiment']}")

sentiment = client.reddit.sentiment("TSLA", period="24h", max_posts=5)
print(f"Overall: {sentiment['overall_sentiment']} ({sentiment['confidence']})")
for post in sentiment["posts_analyzed"]:
    print(f"  [{post['sentiment']}] {post['title'][:60]}")

# Recent posts
posts = client.reddit.subreddit("machinelearning")
for post in posts["posts"]:
    print(f"{post['title']} ({post['score']} pts)")

# Top posts (last week)
top = client.reddit.subreddit_top("machinelearning", time_filter="week", limit=10)
for post in top["posts"]:
    print(f"{post['title']} ({post['score']} pts)")

results = client.github.search_repos("machine learning", sort="stars")
for repo in results["items"]:
    print(f"{repo['full_name']} ⭐ {repo['stargazers_count']}")

repo = client.github.get_repo("facebook", "react")
print(f"{repo['full_name']}: {repo['stargazers_count']} stars, {repo['forks_count']} forks")
for c in repo["top_contributors"][:3]:
    print(f"  {c['login']}: {c['contributions']} commits")

trending = client.trends.get_trending(geo="US")
for topic in trending["searches"]:
    print(f"{topic['title']} - {topic['traffic']}")

prices = client.crypto.get_prices(ids="bitcoin,ethereum")
for coin, data in prices.items():
    print(f"{coin}: {data['usd']:,.2f} USD")

results = client.crypto.search("solana")
for coin in results["coins"]:
    print(f"{coin['name']} ({coin['symbol']}) - Rank #{coin['market_cap_rank']}")

trending = client.crypto.get_trending()
for coin in trending["coins"]:
    print(f"{coin['name']} ({coin['symbol']}) - Score: {coin['score']}")

forecast = client.weather.get_forecast(lat=37.77, lon=-122.42)
for period in forecast["periods"]:
    print(f"{period['name']}: {period['temperature']}°{period['temperatureUnit']} - {period['shortForecast']}")

alerts = client.weather.get_alerts(area="CA")
for alert in alerts["alerts"]:
    print(f"[{alert['severity']}] {alert['event']}: {alert['headline']}")

import requests
results = requests.get("https://api.gettrawl.com/api/search/unified",
    params={"q": "machine learning", "sources": "all", "max_per_source": 3}).json()
for r in results["results"]:
    print(f"[{r['source_type']}] {r['title']}")
print(f"Queried: {', '.join(results['sources_queried'])}")

zip_bytes = client.bulk.download(
    ["dQw4w9WgXcQ", "9bZkp7q19f0"],
    format="jsonl"
)
with open("transcripts.zip", "wb") as f:
    f.write(zip_bytes)

# Preview (no auth)
summary = requests.post("https://api.gettrawl.com/api/ai/preview/summarize",
    json={"text": "Full transcript..."}).json()

# Stored transcript (auth)
summary = requests.post("https://api.gettrawl.com/api/ai/1/summarize",
    headers={"X-API-Key": "trawl_xxx"}).json()

curl -X POST https://api.gettrawl.com/api/ai/1/entities \
  -H "X-API-Key: trawl_your_key"

# Preview (no auth)
result = client.ai.preview_sentiment("Revenue beat expectations by 15%...")
print(f"{result['sentiment_label']}: {result['sentiment_score']}")

# Stored transcript (auth)
result = client.ai.sentiment(transcript_id=42)

webhook = client.webhooks.create(
    url="https://your-app.com/webhooks/trawl",
    events=["job.completed", "job.failed"]
)
print(f"Webhook ID: {webhook['id']}")
print(f"Secret: {webhook['secret']}  # Store this securely!")

client.webhooks.test("wh_abc123")

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your Flask/FastAPI handler:
# signature = request.headers["X-Trawl-Signature"]
# is_valid = verify_webhook(request.body, signature, WEBHOOK_SECRET)

watch = client.watches.create(source_type="earnings_ticker", target="AAPL")
print(f"Watch ID: {watch['id']}")
print(f"Monitoring: {watch['source_type']} / {watch['target']}")

# List watches
watches = client.watches.list()
for w in watches:
    print(f"[{w['status']}] {w['source_type']}: {w['target']}")

# Pause/resume
client.watches.pause(watch["id"])
client.watches.resume(watch["id"])

# Trigger immediate poll
client.watches.trigger(watch["id"])

# Update filters
client.watches.update(watch["id"], filters={"keywords": ["revenue"]})

# Delete
client.watches.delete(watch["id"])

# Attach webhook to watch
client.watches.attach_webhook(watch["id"], webhook_id="wh_abc123")

# Detach webhook
client.watches.detach_webhook(watch["id"], webhook_id="wh_abc123")

# Add to claude_desktop_config.json:
{
  "mcpServers": {
    "trawl": {
      "command": "python",
      "args": ["/path/to/mcp-server/server.py"],
      "env": {
        "BACKEND_URL": "https://api.gettrawl.com",
        "TRAWL_API_KEY": "trawl_your_key"
      }
    }
  }
}

import requests, zipfile, io, json

# 1. Search
results = requests.get("https://api.gettrawl.com/api/search",
    params={"q": "machine learning", "max_results": 10}).json()["results"]

# 2. Bulk download as JSONL
resp = requests.post("https://api.gettrawl.com/api/bulk-download",
    json={"video_ids": [r["video_id"] for r in results], "format": "jsonl"})

# 3. Parse chunks
zf = zipfile.ZipFile(io.BytesIO(resp.content))
chunks = []
for name in zf.namelist():
    if name.endswith(".jsonl"):
        for line in zf.read(name).decode().strip().split("\n"):
            chunks.append(json.loads(line))

# 4. Each chunk has: video_id, title, channel, source_url, text, token_count
#    → Generate embeddings → Upsert to Pinecone with metadata filters

results = requests.get("https://api.gettrawl.com/api/search",
    params={"q": "NVIDIA earnings call Q4", "max_results": 5}).json()

for video in results["results"]:
    transcript = requests.post("https://api.gettrawl.com/api/transcripts/preview",
        json={"url": f"https://youtube.com/watch?v={video['video_id']}"}).json()
    text = " ".join(s["text"] for s in transcript["segments"])
    # → Feed to your sentiment model