Jobs and Polling

All generation endpoints (drone footage, image enhancement, markup) are asynchronous. When you submit a request, the API returns a 202 Accepted response with a job_id. You then poll for the result.

Workflow

1. POST /v1/drone-footage/generate   ->  202 { job_id, status: "queued" }
2. GET  /v1/jobs/{job_id}            ->  200 { status: "running" }
3. GET  /v1/jobs/{job_id}            ->  200 { status: "running" }
4. GET  /v1/jobs/{job_id}            ->  200 { status: "completed", output: {...} }

Job Statuses

Status	Description
`queued`	Job is waiting to be processed
`running`	Job is actively being processed
`awaiting_input`	Job requires human input -- check output for options
`completed`	Job finished successfully -- check output
`failed`	Job failed -- check output for error details

Polling Example

# 1. Submit a job
JOB_ID=$(curl -s -X POST \
  -H "X-API-Key: dome_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "123 Collins St, Melbourne VIC 3000"}' \
  https://api.domeagent.com.au/v1/drone-footage/generate \
  | jq -r '.data.job_id')

echo "Job ID: $JOB_ID"

# 2. Poll until complete
while true; do
  RESPONSE=$(curl -s \
    -H "X-API-Key: dome_live_your_key" \
    https://api.domeagent.com.au/v1/jobs/$JOB_ID)

  STATUS=$(echo $RESPONSE | jq -r '.data.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "awaiting_input" ]; then
    echo $RESPONSE | jq '.data.output'
    break
  fi

  sleep 5
done

Multi-Step Jobs

Some jobs (like markup generation) require human input during processing. These jobs transition through an awaiting_input status instead of going directly to completed.

When a job reaches awaiting_input, the output field contains the data needed for the next step. See the Markup Generation guide for the full multi-step flow.

Recommended Polling Interval

Poll every 5 seconds for the first minute
Then every 15 seconds after that
Jobs typically complete within 30 seconds to 3 minutes depending on the operation

Listing All Jobs

You can list all jobs with optional filters:

# All jobs
curl -H "X-API-Key: dome_live_your_key" \
  https://api.domeagent.com.au/v1/jobs

# Filter by status
curl -H "X-API-Key: dome_live_your_key" \
  "https://api.domeagent.com.au/v1/jobs?status=completed"

# Filter by job type
curl -H "X-API-Key: dome_live_your_key" \
  "https://api.domeagent.com.au/v1/jobs?job_type=drone_footage"

# Pagination
curl -H "X-API-Key: dome_live_your_key" \
  "https://api.domeagent.com.au/v1/jobs?limit=10&offset=0"

Job Response Shape

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "job_type": "drone_footage",
    "status": "completed",
    "input": {
      "address": "123 Collins St, Melbourne VIC 3000"
    },
    "output": {
      "video_url": "https://storage.domeagent.com.au/..."
    },
    "created_at": "2026-02-09T10:00:00.000Z",
    "updated_at": "2026-02-09T10:01:30.000Z",
    "completed_at": "2026-02-09T10:01:30.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:01:30.000Z"
  }
}