All guides
X video

Analyze X posts and attached video captions with tldw.sh

Analyze an X post with its attached video's accessible captions, customize the brief, and retrieve the saved source separately from the generated summary.

tldw.sh can analyze an X post's text together with its attached video's captions. It labels the post and captions as separate sources, so you can see which supports each finding.

Send the post URL and instructions through the API or a connected agent. The backend detects the source, creates an asynchronous job and saves the retrieved text alongside the generated analysis.

Replace the example URL with the public X video you want analyzed. The server selects the available source path:

json
{
  "media": "https://x.com/USER/status/POST_ID",
  "instructions": "Distinguish the author's post from the speaker's claims. Explain the main argument and any caveats in the available text. Be concise.",
  "max_credits": 30
}

Send the body to POST https://api.tldw.sh/v1/analyses with a scoped bearer API key and a stable Idempotency-Key. Save the returned job_id, poll GET /v1/jobs/{job_id}, and retrieve GET /v1/summaries/{summary_id} after completion. See the API quickstart for an executable request sequence.

Use instructions to request a summary, compare claims, ask a question or choose an output language or format. Analysis uses the retrieved source; instructions do not add missing replies, private posts or web access.

Where do the captions come from?

The backend first retrieves post metadata using its configured X retrieval provider, currently TwitterAPI.io. For one attached video, it follows the available HLS subtitle track on X's video CDN and reads the WebVTT caption files.

This is caption extraction, not speech recognition. The caption path does not download the audio/video payload and does not send it to a transcription model. Your application needs only its tldw.sh credential; you do not supply the backend's X provider key.

Caption availability varies by post. Captions visible in one playback environment do not guarantee that a usable track is accessible to the server.

Choose video context or post text only

A plain X URL uses automatic scope. You can make that choice explicit:

json
{
  "media": {
    "type": "x",
    "url": "https://x.com/USER/status/POST_ID",
    "scope": "auto"
  },
  "instructions": "Explain the post and the attached video's spoken argument."
}

To analyze only the post's text, set scope to post and describe that narrower task in your instructions. This deliberately excludes the video. Thread scope is a different operation and does not recursively analyze every attached video in the thread.

If video captions are missing, automatic video analysis can fail. Set scope to post to analyze only the post text.

Read the saved post and captions

After the job succeeds, use the separate transcript read:

text
GET /v1/summaries/{summary_id}/transcript
Authorization: Bearer YOUR_TLDW_API_TOKEN

An X source containing post context and captions uses timed: false and a blocks array. The post-context block is untimed. Caption blocks retain their start_s and end_s timestamps in seconds; the text field combines the saved source text. Do not assume timed: false means the individual blocks have no timing.

The summary endpoint returns the generated analysis. The transcript endpoint returns original source material, even if you requested a summary in another language. Both are owner-private reads requiring summaries:read; neither starts a new processing charge.

Coverage and limits

The caption path supports one attached video with accessible captions or a usable saved transcript. It excludes images, silent visual events, quoted posts and unrelated replies. Multiple-video posts, inaccessible captions, live/incomplete playlists, encrypted tracks and unsupported timing can fail explicitly. Fresh audio transcription is not supported on any plan; no legacy control enables it. CAPTIONS_UNAVAILABLE releases the failed job hold without a processing-credit charge. Blocked or temporary retrieval failures keep their own codes; stop or supply authorized source text instead of retrying automatically.

Use this to extract claims, compare supplied clips or separate a post's framing from its video's speech. Results do not establish platform-wide trends, representativeness, truth or popularity.

Caption processing uses 1 credit per source minute, based on video duration rather than the number of caption words. Free includes 100 monthly caption/text credits, subject to its source-length and concurrency limits. Check current pricing and limits before submitting a long clip.

Reuse saved sources and read transcripts

YouTube source transcripts are reused when a usable saved source exists. X post and Article text reuse your saved snapshot for 24 hours; saved video transcripts can be reused longer. Send refresh_source: true for an explicit fresh X post or X Article fetch. Refresh affects retrieval; it does not grant audio transcription permission.

Submit one link to POST /v1/analyses or MCP analyze_media. The job saves both a summary and its original transcript. Poll the accepted job, then read GET /v1/summaries/SUMMARY_ID and GET /v1/summaries/SUMMARY_ID/transcript, or MCP get_summary and get_transcript, with the same summary ID. Reading saved results starts no new processing or model call. Use list_transcripts and get_saved_transcript to browse saved source pages.

Use the same workflow from an agent

Through MCP, call analyze_media with the same media and instructions, follow the returned job with get_job or wait_job, then use get_summary or get_transcript. JavaScript uses submitAnalysis, getSummary and getTranscript; Python uses submit_analysis, get_summary and get_transcript.

Plugins use these same account permissions and processing rules. They do not bypass caption availability, quota or ownership checks. Start from Connect your agent to choose OAuth or an API-key connection.

Connect your agent

Follow the setup steps for Claude, your coding assistant or your own API client.

Create an account to save summaries and connect your agents.

Connect your agent