Skip to main content

​
Stream Issues

​
Why does my YouTube URL not work?

Trio only works with live streams, not regular videos or past broadcasts (VODs). Check that your URL:
  • Has a red “LIVE” badge on YouTube
  • Is currently broadcasting
  • Is not region-restricted
Error: NOT_LIVESTREAM Solution: Find a currently live stream. You can search YouTube for “live” and filter by “Live” under the Filters menu.

​
Why am I getting “Failed to fetch stream” errors?

This usually means:
  1. The stream is region-restricted and not accessible from our servers
  2. The stream went offline while you were setting up the job
  3. YouTube is rate-limiting requests (temporary)
Error: STREAM_FETCH_FAILED Solution: Try a different stream or wait a few minutes and retry.

​
Why did my job stop after 10 minutes?

Jobs automatically stop after 10 minutes to prevent runaway costs. This is by design. Solution: Set up your webhook handler to restart the job when it receives a job_status event with auto_stopped: true. See Webhooks Guide.

​
Webhook Issues

​
Why am I not receiving webhooks?

  1. URL not publicly accessible - Your webhook URL must be reachable from the internet
  2. Firewall blocking - Check if your firewall allows incoming POST requests
  3. HTTPS required - Some hosting providers require HTTPS
  4. Job not running - Check job status with GET /jobs/{job_id}
Debug steps:
  1. Test with webhook.site first
  2. Check logs endpoint for “webhook” entries
  3. Verify job status is “running”

​
Why is my webhook timing out?

Webhooks must respond within 30 seconds. If your handler takes longer, process the webhook asynchronously. 
@app.post("/webhook")
async def webhook(request: Request, background_tasks: BackgroundTasks):
    payload = await request.json()
    background_tasks.add_task(process_webhook, payload)  # Async
    return {"status": "ok"}  # Return immediately

​
Condition Issues

​
Why is my condition never triggering?

  1. Condition too vague - Be specific about what to look for
  2. Condition not a yes/no question - Use questions like “Is there…?” not “How many…?”
  3. Static stream - Pre-filter skips frames with no motion
Bad: "people" Good: "Are there people walking on the sidewalk?" See Writing Conditions for best practices.

​
Why is my condition triggering too often?

  1. Condition too broad - Add constraints
  2. Prefilter disabled - Enable motion detection to filter static frames
Example improvement: Before: "Is there a car?" After: "Is there a red sports car moving fast?"

​
API Issues

​
What does error code 429 mean?

Error: MAX_JOBS_REACHED You have reached the limit of 10 concurrent jobs. Each job runs for up to 10 minutes. Solution: Cancel an existing job with DELETE /jobs/{id} or wait for one to complete.

​
How do I authenticate API requests?

Include your API key in the Authorization header: 
curl -X POST https://trio.machinefi.com/api/check-once \
  -H "Authorization: Bearer 1Uf-9yE5LzkmSwQBP-MCB" \
  -H "Content-Type: application/json" \
  -d '{"stream_url": "...", "condition": "..."}'

​
What’s the difference between frames, clip, and hybrid modes?

ModeHow it worksLatencyBest for
framesSingle frame snapshot~4sFast checks, static scenes
clip1-10 second video~8sMotion detection, temporal events
hybridFrame + clip combined~12sBest accuracy (default)
Use frames for speed, hybrid for accuracy.

​
What stream types are supported?

PlatformURL FormatNotes
YouTube Liveyoutube.com/watch?v=IDMust be currently live (red LIVE badge)
Twitchtwitch.tv/channelLive streams only
RTSPrtsp://host:port/pathIP cameras, security systems
VODs (past broadcasts) and regular videos are not supported.

​
How do I use Trio with AI agents (MCP)?

Trio supports Model Context Protocol (MCP) for AI agent integration. Claude Desktop config (~/.config/claude/claude_desktop_config.json): 
{
  "mcpServers": {
    "trio": {
      "command": "npx",
      "args": ["mcp-remote", "https://trio.machinefi.com/mcp"]
    }
  }
}
Then ask Claude: “Check the traffic stream at [URL] and tell me if there’s an accident” See MCP Integration for full documentation.

​
My API key isn’t working

  1. Check the format - Use Authorization: Bearer YOUR_KEY (not just the key)
  2. No extra spaces - Copy the key exactly, no trailing spaces
  3. Correct header name - It’s Authorization, not Auth or API-Key
# Correct
-H "Authorization: Bearer sk-abc123..."

# Wrong
-H "Authorization: sk-abc123..."
-H "API-Key: sk-abc123..."

​
Why did my job fail?

Check the job status for details: 
curl https://trio.machinefi.com/api/jobs/YOUR_JOB_ID \
  -H "Authorization: Bearer 1Uf-9yE5LzkmSwQBP-MCB"
Common reasons:
  • Stream went offline - The broadcaster ended the stream
  • Stream URL expired - YouTube URLs expire after ~2 hours
  • Region restricted - Stream not accessible from our servers

​
How do I cancel a job?

Send a DELETE request to the job endpoint: 
curl -X DELETE https://trio.machinefi.com/api/jobs/YOUR_JOB_ID \
  -H "Authorization: Bearer 1Uf-9yE5LzkmSwQBP-MCB"
The job will stop immediately and you’ll receive a final job_status webhook with the stats.

​
Cost & Performance

​
How does pre-filtering save costs?

Trio’s motion detection skips frames that haven’t changed. For static streams (like security cameras), this can reduce VLM API calls by 70-90%. Enable with enable_prefilter: true (default).

​
Why are some frames being skipped?

This is the pre-filter working correctly! It skips frames with no motion to save on VLM costs. Check the frames_skipped stat in job details to see how many frames were filtered.

​
Still Need Help?