Import job monitoring and management endpoints for YouTube and upload processing

Jobs API

The Jobs API allows users to track the status of import jobs for processing YouTube videos and audio file uploads. These jobs handle transcription, content extraction, and note generation.

Import Job Model

id: Unique job identifier (string)
title: Job title/description (string)
status: Job status (string: "PENDING" | "IN_PROGRESS" | "COMPLETED" | "FAILED")
progress: Progress percentage (number, 0-100)
source: Job source (string: "YOUTUBE" | "UPLOAD")
errorMessage: Error details if failed (string, optional)
userId: Owner user ID (string)
noteId: Associated note ID (string, optional)
createdAt: ISO datetime when created (string)
updatedAt: ISO datetime when last updated (string)
completedAt: ISO datetime when completed (string, optional)
note: Associated note information (object, optional)

Note Information Model

id: Note identifier (string)
title: Note title (string)
status: Note processing status (string)
duration: Audio duration in seconds (number, optional)
fileSize: File size in bytes (number, optional)
mimeType: File MIME type (string, optional)
summary: AI-generated summary (string, optional)
date: Note date (string, optional)
createdAt: ISO datetime when created (string)
updatedAt: ISO datetime when last updated (string)
course: Associated course information (object, optional)

Endpoints

All job endpoints require authentication and are scoped to the authenticated user.

Get Job Statistics

Retrieve comprehensive job statistics including counts by status, success rate, recent jobs, and queue information.

GET /api/jobs/stats

Response (200)

{
  "success": true,
  "data": {
    "total": 45,
    "byStatus": {
      "pending": 2,
      "inProgress": 1,
      "completed": 40,
      "failed": 2
    },
    "successRate": 89,
    "recentJobs": [
      {
        "id": "job_abc123",
        "title": "Processing: Biology Lecture 5",
        "status": "COMPLETED",
        "progress": 100,
        "source": "YOUTUBE",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "completedAt": "2024-01-15T10:03:45.000Z"
      },
      {
        "id": "job_def456", 
        "title": "Processing: audio_lecture.mp3",
        "status": "IN_PROGRESS",
        "progress": 75,
        "source": "UPLOAD",
        "createdAt": "2024-01-15T09:45:00.000Z",
        "completedAt": null
      }
    ],
    "queueStats": {
      "waiting": 2,
      "active": 1,
      "completed": 42,
      "failed": 2,
      "total": 47
    }
  }
}

Errors:

401: Authentication required
500: Failed to fetch statistics

Get All Jobs

Retrieve all import jobs for the authenticated user with filtering, sorting, and pagination.

GET /api/jobs

# Filter by status
GET /api/jobs?status=IN_PROGRESS

# Filter by source
GET /api/jobs?source=YOUTUBE

# With pagination and sorting
GET /api/jobs?limit=20&offset=0&sortBy=createdAt&sortOrder=desc

Query Parameters

status: Filter by job status (optional: "PENDING" | "IN_PROGRESS" | "COMPLETED" | "FAILED")
source: Filter by job source (optional: "YOUTUBE" | "UPLOAD")
limit: Number of jobs to return (optional, 1-100, default: 20)
offset: Number of jobs to skip (optional, default: 0)
sortBy: Field to sort by (optional: "createdAt" | "updatedAt" | "completedAt", default: "createdAt")
sortOrder: Sort order (optional: "asc" | "desc", default: "desc")

Response (200)

{
  "success": true,
  "data": {
    "jobs": [
      {
        "id": "job_abc123",
        "title": "Processing: Biology Lecture 5",
        "status": "COMPLETED",
        "progress": 100,
        "source": "YOUTUBE",
        "errorMessage": null,
        "userId": "user_123",
        "noteId": "note_abc123",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:03:45.000Z",
        "completedAt": "2024-01-15T10:03:45.000Z",
        "note": {
          "id": "note_abc123",
          "title": "Biology Lecture 5",
          "status": "COMPLETED",
          "duration": 3600,
          "fileSize": 45678901,
          "mimeType": "video/mp4",
          "date": "2024-01-15",
          "course": null
        }
      },
      {
        "id": "job_def456",
        "title": "Processing: audio_lecture.mp3",
        "status": "IN_PROGRESS",
        "progress": 75,
        "source": "UPLOAD",
        "errorMessage": null,
        "userId": "user_123",
        "noteId": "note_def456",
        "createdAt": "2024-01-15T09:45:00.000Z",
        "updatedAt": "2024-01-15T09:47:30.000Z",
        "completedAt": null,
        "note": {
          "id": "note_def456",
          "title": "Audio Lecture",
          "status": "PROCESSING",
          "duration": 2700,
          "fileSize": 12345678,
          "mimeType": "audio/mpeg",
          "date": "2024-01-15",
          "course": {
            "id": "course_abc123",
            "name": "Biology 101",
            "color": "green",
            "emoji": "🧬"
          }
        }
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "hasMore": true,
      "nextOffset": 20
    }
  }
}

Errors:

400: Invalid query parameters
401: Authentication required
500: Failed to fetch jobs

Get Job by ID

Retrieve a specific import job with detailed information including associated note and course data.

GET /api/jobs/{id}

Path Parameters

id: Job ID (required)

Response (200)

{
  "success": true,
  "data": {
    "id": "job_abc123",
    "title": "Processing: Biology Lecture 5",
    "status": "COMPLETED",
    "progress": 100,
    "source": "YOUTUBE",
    "errorMessage": null,
    "userId": "user_123",
    "noteId": "note_abc123",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:03:45.000Z",
    "completedAt": "2024-01-15T10:03:45.000Z",
    "note": {
      "id": "note_abc123",
      "title": "Biology Lecture 5",
      "status": "COMPLETED",
      "duration": 3600,
      "fileSize": 45678901,
      "mimeType": "video/mp4",
      "summary": "This lecture covers cell division processes including mitosis and meiosis...",
      "date": "2024-01-15",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:03:45.000Z",
      "course": {
        "id": "course_abc123",
        "name": "Biology 101",
        "color": "green",
        "emoji": "🧬"
      }
    }
  }
}

Errors:

400: Invalid job ID
401: Authentication required
404: Job not found
500: Failed to fetch job

Cancel Job

Cancel a pending or in-progress import job. Completed or failed jobs cannot be cancelled.

POST /api/jobs/{id}/cancel

Path Parameters

id: Job ID (required)

Response (200)

{
  "success": true,
  "message": "Job cancelled successfully"
}

Errors:

400: Invalid job ID, or cannot cancel completed/failed job
401: Authentication required
404: Job not found
500: Failed to cancel job

Delete Job

Delete a completed or failed import job from the database. Active jobs (pending or in-progress) cannot be deleted and must be cancelled first.

DELETE /api/jobs/{id}

Path Parameters

id: Job ID (required)

Response (200)

{
  "success": true,
  "message": "Job deleted successfully"
}

Errors:

400: Invalid job ID, or cannot delete active job
401: Authentication required
404: Job not found
500: Failed to delete job

Job Processing Flow

YouTube Import Jobs

PENDING: Job queued for processing
IN_PROGRESS: Downloading video and extracting audio
IN_PROGRESS: Transcribing audio content
IN_PROGRESS: Generating summary and processing content
COMPLETED: Note created with transcript and summary
FAILED: Error occurred during processing

Upload Import Jobs

PENDING: Job queued for processing
IN_PROGRESS: Processing uploaded audio file
IN_PROGRESS: Transcribing audio content
IN_PROGRESS: Generating summary and processing content
COMPLETED: Note created with transcript and summary
FAILED: Error occurred during processing

Job Status Descriptions

PENDING: Job is queued and waiting to be processed
IN_PROGRESS: Job is currently being processed
COMPLETED: Job finished successfully with note created
FAILED: Job failed due to error (see errorMessage for details)

Progress Tracking

Progress values represent the overall completion percentage:

0-25%: Initial setup and file processing
25-75%: Audio transcription (longest phase)
75-95%: Content processing and AI summary generation
95-100%: Final note creation and cleanup

Common Error Scenarios

YouTube URL Invalid: Invalid or private YouTube URL
File Too Large: Uploaded file exceeds size limits
Unsupported Format: Audio/video format not supported
Transcription Failed: Audio quality too poor for transcription
Rate Limit Exceeded: Too many concurrent jobs
Network Timeout: Download or processing timeout

Import jobs integrate with:

Notes API: Creates note records upon successful completion
Courses API: Associates imported content with courses
Queue System: Manages background job processing
File Storage: Handles audio/video file storage

Jobs API

On this page