Jobs API

GET /v1/jobs/{job_id} — Get Job Status

GET /v1/jobs/{job_id}

Retrieve the current status, progress, metadata, and artifact links for a specific render job.

Path Parameters

Parameter	Type	Description
job_id	UUID	The job identifier returned from POST /v1/render

Response (200 OK)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100.0,
  "map_title": "Kano - Prima Stella [Caged]",
  "created_at": "2026-06-08T10:00:00Z",
  "updated_at": "2026-06-08T10:05:30Z",
  "error_message": null,
  "config": {
    "skin": "Default",
    "resolution": "1080p",
    "bg_dim": 0.95,
    "motion_blur": true,
    "storyboard": true,
    "video": false,
    "snaking_in": true,
    "snaking_out": true,
    "hit_error_meter": true,
    "key_overlay": true,
    "replay_stats": {
      "300s": 1245,
      "100s": 12,
      "50s": 0,
      "misses": 1,
      "max_combo": 1847,
      "star_rating": "6.23",
      "pp": 425.8
    }
  },
  "has_analytics": true,
  "artifacts": {
    "video_url": "/v1/artifacts/videos/550e8400-e29b-41d4-a716-446655440000.mp4",
    "thumbnail_url": "/v1/artifacts/thumbnails/550e8400-e29b-41d4-a716-446655440000.jpg",
    "logs_url": "/v1/artifacts/logs/550e8400-e29b-41d4-a716-446655440000.log",
    "analytics_url": "/v1/jobs/550e8400-e29b-41d4-a716-446655440000/analytics"
  }
}

Job Status Values

Status	Description
queued	Job accepted, waiting for worker dispatch
downloading	Worker is downloading replay, beatmap, and skin assets
rendering	danser-go is actively rendering the video
completed	Video rendered and uploaded, artifacts available
failed	Job failed — check error_message for details

Error Response

Status	Condition
404	Job with given ID not found

---

GET /v1/jobs — List Jobs

GET /v1/jobs

Retrieve a paginated list of all render jobs, ordered by creation time (newest first).

Query Parameters

Parameter	Type	Default	Range	Description
limit	int	20	1–100	Maximum number of jobs to return
offset	int	0	≥ 0	Pagination offset
status	string	(none)	—	Filter by job status (queued, rendering, completed, failed)

Example

# Get the 10 most recent completed jobs
curl "http://localhost:8727/v1/jobs?limit=10&status=completed"

Response (200 OK)

{
  "total": 142,
  "jobs": [
    {
      "job_id": "...",
      "status": "completed",
      "progress": 100.0,
      "map_title": "Kano - Prima Stella [Caged]",
      "created_at": "2026-06-08T10:00:00Z",
      "updated_at": "2026-06-08T10:05:30Z",
      "error_message": null,
      "config": {},
      "artifacts": {
        "video_url": "/v1/artifacts/videos/....mp4",
        "thumbnail_url": "/v1/artifacts/thumbnails/....jpg",
        "logs_url": "/v1/artifacts/logs/....log"
      }
    }
  ]
}

Error Masking

In production mode (DEBUG=false), error_message is replaced with a generic message: "An internal rendering error occurred." to prevent information leakage.

---

GET /v1/jobs/{job_id}/analytics — Get Analytics Data

GET /v1/jobs/{job_id}/analytics

Retrieve detailed replay analytics including timing offsets, aim coordinates, hit accuracy, and life bar tracking over the duration of the map.

Path Parameters

Parameter	Type	Description
job_id	UUID	The job identifier

Response (200 OK)

Returns a highly detailed AnalyticsResponse object containing deep inspection metrics of the player's performance.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "identity": {
    "username": "Peppy",
    "beatmap_hash": "a1b2c3d4e5f6...",
    "game_mode": "osu!standard"
  },
  "performance": {
    "score": 1234567,
    "max_combo": 1847,
    "perfect": false,
    "mods": ["Hidden", "DoubleTime"],
    "pp_earned": 425.8
  },
  "hit_counts": {
    "300s": 1245,
    "100s": 12,
    "50s": 0,
    "misses": 1,
    "geki": 140,
    "katu": 10
  },
  "life_bar": [
    { "time": 1050, "health": 1.0 },
    { "time": 2100, "health": 0.95 }
  ],
  "frames": [
    { "t": 0, "x": 256, "y": 192, "keys": 0 },
    { "t": 16, "x": 258, "y": 190, "keys": 1 }
  ]
}

Async Polling Note

Replay frames are extracted and uploaded to MinIO asynchronously. If the render job is still queued, downloading, or rendering, and the frame upload has not yet completed, the endpoint will return a 202 Accepted response.

Status	Description
200 OK	Analytics data is available and returned.
202 Accepted	The job exists, but analytics extraction is still in progress. Check back later.
404 Not Found	The specified job does not exist, or failed before analytics could be processed.