Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.machinefi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Goal

Track async jobs with predictable polling logic and clean terminal-state handling.

​
Polling Workflow

  1. Create a job with live-monitor or live-digest.
  2. Store returned job_id.
  3. Poll GET /jobs/{job_id} on an interval.
  4. Exit on terminal status: completed, stopped, or failed.

​
Reference Implementation (Python)

import time
import requests

BASE = "https://trio.machinefi.com/api"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}

start = requests.post(
    f"{BASE}/live-monitor",
    headers=HEADERS,
    json={
        "stream_url": "https://www.youtube.com/watch?v=jfKfPfyJRdk",
        "condition": "Is there a cat visible?"
    },
    timeout=30,
)
start.raise_for_status()
job_id = start.json()["job_id"]

while True:
    status_resp = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
    status_resp.raise_for_status()
    job = status_resp.json()
    status = job["status"]

    if status in ("completed", "stopped", "failed"):
        print(f"Terminal status: {status}")
        print(job.get("stats", {}))
        break

    time.sleep(5)
  • Start with 3-5 second intervals.
  • Add request timeout guards in your client.
  • Treat 404 JOB_NOT_FOUND as terminal for stale/expired job IDs.
  • Persist last known status for auditing.

​
When to Switch Away

Use webhooks or SSE when:
  • you need lower-latency push updates
  • many clients are polling the same stream
  • frontend UX needs live progress updates

​
Next Steps