Jobs - Naïve

CLI First

# List active jobs
naive jobs --status processing --limit 10

# Get one job
naive jobs get <job-id>

# Cancel a running job
naive jobs cancel <job-id>

The Jobs System

All image/video generation operations and deep research go through a unified jobs system. The pattern is always:

Submit → get job_id (202 response)
Poll → check status via GET /v1/jobs/:id
Complete → job finishes, credits charged, result available

Job Statuses

Status	Meaning
`queued`	Submitted, waiting to start
`processing`	Running (may include progress %)
`completed`	Done — result available, credits charged
`failed`	Error — no credits charged
`cancelled`	Cancelled by user — no credits charged

Listing Jobs

GET /v1/jobs?status=processing&limit=10

Filter by status: queued, processing, completed, failed, cancelled.

Getting Job Details

GET /v1/jobs/:id

{
  "id": "job-uuid",
  "type": "video_generation",
  "status": "completed",
  "progress": 100,
  "model": "fal-ai/kling-video/v3/pro/text-to-video",
  "result": { "..." },
  "error": null,
  "credits_used": 50,
  "provider_request_id": "req-123",
  "created_at": "2026-05-02T10:30:00Z",
  "started_at": "2026-05-02T10:30:01Z",
  "completed_at": "2026-05-02T10:31:02Z",
  "metadata": { "estimated_seconds": 60 }
}

Cancelling a Job

DELETE /v1/jobs/:id

Only works for jobs in queued or processing state.

Job Types

Type	Created By
`image_generation`	`POST /v1/images/generate`
`video_generation`	`POST /v1/video/generate`
`deep_research`	`POST /v1/search/research` (thorough/exhaustive)

Convenience Aliases

Each primitive has its own status endpoint that filters to its job type:

GET /v1/images/:jobId — same as /v1/jobs/:id but validates it’s an image job
GET /v1/video/:jobId — same as /v1/jobs/:id but validates it’s a video job

​CLI First

​The Jobs System

​Job Statuses

​Listing Jobs

​Getting Job Details

​Cancelling a Job

​Job Types

​Convenience Aliases