Concepts

Background jobs

AI images and videos, brand learning and clipping run in the background: wait for them, or follow them.

Some actions take longer than a request should: generating an image (about 40 seconds) or a video (one to three minutes), learning a brand from its website, clipping a long video, making an AI actor ad.

These endpoints start the job and wait for it a while before answering:

Done in time: 200 with the result ("status": "done", and the media_id).
Still running: 202 with "status": "running", the job's id and next, which names the endpoint to follow it with.

{
  "generation_id": "6f1c…",
  "status": "running",
  "progress": 40,
  "next": "Still being made. Call GET /api/v1/media/generations/{generation_id} generation_id=6f1c… to wait for it."
}

How long to wait

Endpoints marked with a wait parameter take ?wait=<seconds>, from 0 to 290. The default is 50. wait=0 answers at once; a long wait saves you a loop.

tracee media generate-image --prompt "A clean product shot, warm light" --platform linkedin --wait 120
tracee media generation <generation_id>        # follow it

In the CLI, a job that's still running prints the command that follows it.

Job	Start	Follow
AI image	`POST /media/images`	`GET /media/generations/{generation_id}`
AI video	`POST /media/videos`	`GET /media/generations/{generation_id}`
Brand learning	`POST /brand/learn`	`GET /brand/learn/{run_id}`
Clipping	`POST /clips`	`GET /clips/{job_id}` (waits up to about 45 seconds)
AI actor ad	`POST /ai-actor-videos`	`GET /ai-actor-videos/{job_id}`
Radar check, competitor discovery, inbox sync	`POST /radar/refresh`, `/radar/discover`, `/inbox/sync`	Read the results a minute later