YTAPI.devDocs

Get batch status

getBatchJob(id): BatchJobResponse

GET
https://api.ytapi.dev/v1/batch/{id}

Poll or inspect the status and results of an asynchronous batch job. While running, status will be pending (waiting in queue for an execution slot) or processing (actively running). Once finished, status will be completed (or failed) with populated results and exact credits_deducted.

Lifecycle States

  • pending: The job is waiting in the queue for available global and per-account execution slots. Queued jobs automatically start in FIFO order as earlier jobs complete. If a job remains queued longer than the queue timeout (default 5 minutes), it fails safely with 0 credits deducted.
  • processing: An execution slot has been acquired; tasks are actively running across concurrent workers.
  • completed: All tasks finished; results are available and final credits have been settled.
  • failed: The job encountered a fatal error, was canceled, or timed out in queue.
API Key

All requests require a valid API key from the developer dashboard.

Headers: Authorization: Bearer YOUR_API_KEYorX-API-Key: YOUR_API_KEY

See Authentication for headers and rate limits.

Path Parameters

ParameterTypeRequiredDescription
idpath
stringYes

The unique batch job ID returned by POST /v1/batch.

Response (HTTP 200)

{
  "id": string,                  // Batch job identifier
  "status": string,              // Lifecycle state: "pending", "processing", "completed", or "failed"
  "total": number,               // Total tasks in the batch
  "successful": number,          // Number of successfully finished tasks (status: 200)
  "failed": number,              // Number of failed tasks
  "credits_deducted": number,    // Actual billable credits deducted
  "duration_ms": number,         // Execution time in milliseconds
  "results": [                   // Array of individual task results once completed
    {
      "id": string,              // Caller-specified task id
      "type": string,            // "transcript" or "basic_info"
      "video_id": string,        // YouTube video ID
      "status": number,          // HTTP status code (200, 404, etc.)
      "data": any,               // Extracted transcript or video metadata payload (when status=200)
      "error": {                 // Structured error envelope (when status != 200)
        "code": string,
        "message": string
      }
    }
  ],
  "created_at": string,          // ISO 8601 creation timestamp
  "completed_at": string | null, // ISO 8601 completion timestamp
  "expires_at": string | null    // ISO 8601 timestamp when batch results expire (7 days retention)
}

[!NOTE] Data Retention: Batch results are retained in cloud storage for 7 days after job completion. After expires_at, results are purged and the results array is no longer available. Metadata (status, credits_deducted, timestamps) remains accessible.