> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Subtitle Task Status

> Retrieves the current status of a subtitle task using the specified `task_id`.

Monitor the progress of your subtitle generation in real-time with our status tracking endpoint. This essential companion to our subtitle service lets you check the current state of your media processing job across every requested language. By polling this endpoint, you can track your subtitle task's lifecycle and handle potential processing issues proactively.

<Card cta="Go to Subtitle Endpoint Page" icon="info" arrow={false} href="create-subtitle">
  This endpoint works in conjunction with the main `/sub` endpoint, which initiates the subtitle process and provides the `task_id` required for status checks.
</Card>

## Implementing Status Checking

Here's how to implement subtitle status monitoring in your application using Python:

```python [expandable] theme={null}
import requests
import time

# Your API authentication
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
    "Content-Type": "application/json"
}

def check_subtitle_status(task_id):
    """
    Polls the status endpoint to track a subtitle task's progress.
    Continues checking until the task reaches a terminal state.
    """
    if not task_id:
        print("Error: No task ID provided")
        return None

    terminal_states = ["SUCCESS", "ERROR"]
    current_status = None

    while current_status not in terminal_states:
        try:
            # Make the status request
            response = requests.get(
                f"https://client.camb.ai/apis/sub/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Extract the status information
            status_data = response.json()
            current_status = status_data.get("status")

            # Display current progress information
            print(f"Status: {current_status}")
            if current_status == "PENDING":
                time.sleep(15)
                continue

            # Handle completed state
            if current_status == "SUCCESS":
                print("Subtitle generation completed successfully!")
                return status_data

            # Handle failed state
            if current_status == "ERROR":
                print(f"Subtitle generation failed: {status_data.get('message')}")
                return status_data

            # Wait before next check to avoid excessive requests
            time.sleep(15)  # Poll every 15 seconds

        except requests.exceptions.RequestException as e:
            print(f"Error checking subtitle status: {e}")
            if hasattr(e, 'response') and e.response is not None:
                print(f"Response content: {e.response.text}")
            return None

    return None

# Example usage with a task_id from a subtitle request
task_id = "your_task_id"  # Replace with your actual task ID
final_status = check_subtitle_status(task_id)
```

## Best Practices for Status Monitoring

Ensure efficient tracking of your subtitle tasks with these professional recommendations:

1. **Optimized Polling Intervals**: Start with 15-second intervals and gradually increase to 60 seconds for long media files
2. **Terminal State Handling**: Implement robust error handling for both success and failure scenarios


## OpenAPI

````yaml get /sub/{task_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /sub/{task_id}:
    get:
      tags:
        - Apis
      summary: Get Subtitle Task Status
      operationId: get_subtitle_task_status_sub__task_id__get
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            title: Task ID
            description: >-
              A unique identifier for the task. This is used to query the status
              of the subtitle task that is running. It is returned when a create
              request is made for subtitle generation.
            example: ''
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrchestratorPipelineResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    OrchestratorPipelineResult:
      properties:
        status:
          $ref: '#/components/schemas/TaskStatus'
        run_id:
          type:
            - integer
            - 'null'
          title: Run ID
      type: object
      title: OrchestratorPipelineResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskStatus:
      type: string
      enum:
        - SUCCESS
        - PENDING
        - TIMEOUT
        - ERROR
        - PAYMENT_REQUIRED
      title: TaskStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        The `x-api-key` is a custom header required for authenticating requests
        to our API. Include this header in your request with the appropriate API
        key value to securely access our endpoints. You can find your API key(s)
        in the 'API' section of our studio website.

````