# Job lifecycle Understand Lingopal job states, poll workflow status, inspect registration metadata, and rerun work safely. URL: /guides/jobs/job-lifecycle Use the status endpoint while processing. Use the job endpoint for registration metadata and related links. ## Check workflow status [#check-workflow-status] ```bash export LINGOPAL_API_KEY="your-api-key" export JOB_ID="replace-with-job-id" curl "https://api.lingopal.ai/v2/jobs/$JOB_ID/status" \ -H "X-API-Key: $LINGOPAL_API_KEY" ``` ## GET /v2/jobs/{job_id}/status ```json { "openapi": "3.1.0", "info": { "title": "Get registered job status", "description": "Lingopal v2 public API for text translation, storage uploads, registered jobs, job workflows, and job outputs.", "version": "v2" }, "servers": [ { "url": "https://vod-api.lingopal-dev.com" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/v2/jobs/{job_id}/status": { "get": { "tags": [ "Jobs" ], "summary": "Get registered job status", "description": "Returns current processing status for a reusable registered job.", "operationId": "getJobStatus", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Reusable registered job ID returned by `/v2/jobs/register` or `/v2/jobs/upload-and-register`.", "examples": [ "job_123" ], "title": "Job Id" }, "description": "Reusable registered job ID returned by `/v2/jobs/register` or `/v2/jobs/upload-and-register`." } ], "responses": { "200": { "description": "Current job processing status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" }, "example": { "job_id": "job_123", "job_type": "video", "status": "processing", "stage": "translating", "sub_stage": "dubbing", "workflows": { "translation": { "status": "processing", "languages": [ { "target_language": "es", "status": "processing" }, { "target_language": "fr", "status": "queued" } ] } }, "outputs": { "transcript": true, "subtitles": false }, "updated_at": "2026-07-07T16:10:00Z" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "example": { "detail": "Job Not Found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "tags": [ { "name": "Jobs", "description": "Inspect registered job metadata and processing status." } ], "components": { "schemas": { "JobStatusResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Reusable registered job ID." }, "job_type": { "type": "string", "enum": [ "video", "audio", "document" ], "title": "Job Type", "description": "Registered job type." }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ], "title": "Status", "description": "Current active workflow processing status." }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stage", "description": "Best-effort internal processing stage." }, "sub_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sub Stage", "description": "Best-effort internal processing sub-stage." }, "workflows": { "additionalProperties": { "$ref": "#/components/schemas/JobWorkflowStatus" }, "propertyNames": { "enum": [ "translation", "subtitles", "transcription", "republish" ] }, "type": "object", "title": "Workflows", "description": "Current workflow statuses keyed by v2 workflow type." }, "outputs": { "additionalProperties": { "type": "boolean" }, "type": "object", "title": "Outputs", "description": "Best-effort output availability flags." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Processing error when the job failed." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last job update timestamp." } }, "type": "object", "required": [ "job_id", "job_type", "status" ], "title": "JobStatusResponse", "examples": [ { "job_id": "job_123", "job_type": "video", "outputs": { "subtitle": false, "transcript": true }, "stage": "translating", "status": "processing", "sub_stage": "dubbing", "updated_at": "2026-07-07T16:10:00Z", "workflows": { "translation": { "languages": [ { "status": "processing", "target_language": "es" }, { "status": "queued", "target_language": "fr" } ], "status": "processing" } } } ] }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "JobWorkflowStatus": { "properties": { "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ], "title": "Status", "description": "Current aggregate workflow status." }, "languages": { "items": { "$ref": "#/components/schemas/JobLanguageStatus" }, "type": "array", "title": "Languages" } }, "type": "object", "required": [ "status" ], "title": "JobWorkflowStatus" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "JobLanguageStatus": { "properties": { "target_language": { "type": "string", "title": "Target Language", "description": "Target locale code." }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ], "title": "Status", "description": "Current status for this language." } }, "type": "object", "required": [ "target_language", "status" ], "title": "JobLanguageStatus" } }, "securitySchemes": { "APIKeyHeader": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } } } ``` Use the [API Reference entry for getJobStatus](/reference/jobs/getJobStatus) for full status fields and response schema. Top-level status is one of `queued`, `processing`, `completed`, or `failed`. The response can also include: * `workflows.translation` and `workflows.subtitles` * `outputs` availability flags * `stage` and `sub_stage` * `error` when processing fails * `updated_at` Poll every few seconds, increase the interval for long media, and stop at `completed` or `failed`. ## Inspect registration metadata [#inspect-registration-metadata] ```bash export LINGOPAL_API_KEY="your-api-key" export JOB_ID="replace-with-job-id" curl "https://api.lingopal.ai/v2/jobs/$JOB_ID" \ -H "X-API-Key: $LINGOPAL_API_KEY" ``` ## GET /v2/jobs/{job_id} ```json { "openapi": "3.1.0", "info": { "title": "Get registered job", "description": "Lingopal v2 public API for text translation, storage uploads, registered jobs, job workflows, and job outputs.", "version": "v2" }, "servers": [ { "url": "https://vod-api.lingopal-dev.com" } ], "security": [ { "APIKeyHeader": [] } ], "paths": { "/v2/jobs/{job_id}": { "get": { "tags": [ "Jobs" ], "summary": "Get registered job", "description": "Returns metadata for a reusable registered job.", "operationId": "getJob", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Reusable registered job ID returned by `/v2/jobs/register` or `/v2/jobs/upload-and-register`.", "examples": [ "job_123" ], "title": "Job Id" }, "description": "Reusable registered job ID returned by `/v2/jobs/register` or `/v2/jobs/upload-and-register`." } ], "responses": { "200": { "description": "Registered job metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" }, "example": { "job_id": "job_123", "name": "Product Demo", "job_type": "video", "source_url": "https://cdn.example.com/uploads/product-demo.mp4", "created_at": "2026-07-07T16:00:00Z", "updated_at": "2026-07-07T16:05:00Z", "links": { "self": "/v2/jobs/job_123", "status": "/v2/jobs/job_123/status", "translations": "/v2/jobs/job_123/translations", "subtitles": "/v2/jobs/job_123/subtitles" } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "example": { "detail": "Job Not Found" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "tags": [ { "name": "Jobs", "description": "Inspect registered job metadata and processing status." } ], "components": { "schemas": { "JobResponse": { "properties": { "job_id": { "type": "string", "title": "Job Id", "description": "Reusable registered job ID." }, "name": { "type": "string", "title": "Name", "description": "Job display name." }, "job_type": { "type": "string", "enum": [ "video", "audio", "document" ], "title": "Job Type", "description": "Registered job type." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Url", "description": "Original or registered source URL." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Job creation timestamp." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Job update timestamp." }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links", "description": "Related v2 job links." } }, "type": "object", "required": [ "job_id", "name", "job_type" ], "title": "JobResponse", "examples": [ { "created_at": "2026-07-07T16:00:00Z", "job_id": "job_123", "job_type": "video", "links": { "self": "/v2/jobs/job_123", "status": "/v2/jobs/job_123/status", "subtitles": "/v2/jobs/job_123/subtitles", "translations": "/v2/jobs/job_123/translations" }, "name": "Product Demo", "source_url": "https://cdn.example.com/uploads/product-demo.mp4", "updated_at": "2026-07-07T16:05:00Z" } ] }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "APIKeyHeader": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } } } ``` Use the [API Reference entry for getJob](/reference/jobs/getJob) for complete response metadata. This returns the job name, type, source URL, timestamps, and related links. It is not the primary workflow-progress response. ## Rerun safely [#rerun-safely] Wait for the active workflow to finish before starting another run. For translation, `reset` defaults to `true` and prunes stale target-language state before refreshing progress. For subtitles, `reset` defaults to `false`. Set either value explicitly when rerun behavior matters.