Batch Generation API

Generate multiple quiz questions as a background job.

Start Batch Generation

POST /api/admin/quizzes/batches/{batchId}/run

Enqueues a batch generation job and returns immediately.

Response

HTTP/1.1 202 Accepted

{
  "jobId": "batch-gen-abc123",
  "message": "Batch generation started"
}

Poll Batch Status

GET /api/admin/quizzes/batches/{batchId}/status

Returns the current status of all items in the batch.

Response

{
  "items": [
    {
      "id": "item-1",
      "proficiencyLevel": "N5",
      "difficulty": "easy",
      "status": "generated",
      "elapsedMs": 3200
    },
    {
      "id": "item-2",
      "proficiencyLevel": "N5",
      "difficulty": "medium",
      "status": "generating"
    },
    {
      "id": "item-3",
      "proficiencyLevel": "N4",
      "difficulty": "hard",
      "status": "queued"
    }
  ],
  "totalItems": 3
}

Item Status

Status	Description
queued	Waiting to be processed
generating	AI generation in progress
generated	Successfully generated
failed	Generation failed (see errorMessage)
approved	Reviewed and approved by teacher
published	Published and available to students

Frontend Integration

The frontend polls the status endpoint every 3 seconds:

const pollInterval = setInterval(async () => {
  const res = await fetch(`/api/admin/quizzes/batches/${batchId}/status`);
  const data = await res.json();
  updateProgress(data.items);

  const allDone = data.items.every(
    (i) => ["generated", "failed", "approved", "published"].includes(i.status)
  );
  if (allDone) clearInterval(pollInterval);
}, 3000);

Credits

• Credits are reserved when the batch job starts
• Used credits are charged per successful generation
• Unused credits are refunded when the batch completes