> ## 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.

# Use Polling

> Track async jobs with `GET /jobs/{job_id}`

## 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)

```python theme={null}
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)
```

## Recommended Practices

* 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

* Push callbacks: [Use Webhooks](/guides/webhooks)
* Streaming events: [Use SSE Streaming](/guides/sse-streaming)
* Status semantics: [Get Job Details](/api-reference/jobs-get)