> ## 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 Translation Task Status

> Monitor the progress of your translation tasks with real-time status updates, enabling you to track completion and retrieve translated content when ready.

This endpoint serves as your window into the translation process, allowing you to monitor the status of tasks you've submitted through the `/translate` endpoint. By providing the unique `task_id` you received when initiating a translation, you can check whether your translation is still being processed, has completed successfully, or encountered an issue. When translation is complete, this endpoint also delivers your translated text.

## Understanding the Translation Lifecycle

When you submit a translation request, it goes through several stages before completion. This endpoint keeps you informed about which stage your task has reached:

### Status Types

The `status` field in the response will contain one of these values:

* **`PENDING`**: Your translation is currently in the processing queue or actively being translated. This indicates that everything is working as expected, but the translation is not yet complete. Continue polling at reasonable intervals.

* **`SUCCESS`**: The translation process has completed successfully. When you receive this status, your `run_id` is returned which the identifier that you would use to fetch your translations by using the [`/translation-result/{run_id}`](get-translation-run-result)

* **`ERROR`**: Something went wrong during the translation process. This could be due to invalid input parameters, server issues, or problems with the translation engine. The response may include additional details about the nature of the error.

* **`TIMEOUT`**: The translation task exceeded the maximum allowed processing time. This typically happens with extremely large translation requests or during periods of high system load. Consider breaking your request into smaller batches.

* **`PAYMENT_REQUIRED`**: Your account does not have sufficient credits or permissions to complete this translation. Please check your subscription status or contact support for assistance.

## Recommended Polling Strategy

Asynchronous operations like translation require a thoughtful approach to status checking:

1. **Start with short intervals**: Initially check every 1-2 seconds for very short translations
2. **Use exponential backoff**: Gradually increase the time between checks (e.g., doubling the wait time after each check)
3. **Set a maximum interval**: Don't let the wait time grow beyond 10-15 seconds
4. **Implement a timeout**: Establish a maximum total wait time for your application

This approach balances responsiveness with server efficiency, ensuring you get your translations promptly without overloading the system with unnecessary requests.

## Example: Monitoring Translation Progress

Here's how you might implement status checking for a translation task:

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

def check_translation_status(task_id, api_key, base_url="https://client.camb.ai/apis"):
    """
    Check the status of a translation task with exponential backoff.

    Parameters:
    -----------
    task_id : str
        The unique identifier for the translation task
    api_key : str
        Your API authentication key
    base_url : str
        The base URL for the API endpoints

    Returns:
    --------
    dict
        The final response containing translations if successful
    """
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json"
    }

    # Initial polling parameters
    wait_time = 1  # Start with 1 second
    max_wait_time = 10  # Maximum seconds between polls
    max_total_wait = 300  # Maximum total seconds to wait (5 minutes)
    start_time = time.time()

    while (time.time() - start_time) < max_total_wait:
        # Get current status
        response = requests.get(
            f"{base_url}/translate/{task_id}",
            headers=headers
        )

        # Check for API errors
        if response.status_code != 200:
            print(f"Error checking status: HTTP {response.status_code}")
            return None

        status_data = response.json()
        current_status = status_data.get("status")

        # Handle each possible status
        if current_status == "SUCCESS":
            print("✅ Translation completed successfully!")
            return status_data  # Contains translations

        elif current_status == "PENDING":
            elapsed = round(time.time() - start_time)
            print(f"⏳ Translation in progress... ({elapsed}s elapsed)")

        elif current_status == "ERROR":
            print("❌ Translation failed with an error.")
            return status_data  # May contain error details

        elif current_status == "TIMEOUT":
            print("⏰ Translation timed out on the server.")
            return status_data

        elif current_status == "PAYMENT_REQUIRED":
            print("💰 Additional payment or credits required.")
            return status_data

        # Wait before checking again, with exponential backoff
        time.sleep(wait_time)
        wait_time = min(wait_time * 2, max_wait_time)  # Double wait time but cap it

    # If we've reached here, we've exceeded our maximum wait time
    print("🛑 Client-side timeout: Maximum wait time exceeded")
    return None

# Example usage:
api_key = "your-api-key"  # Replace with your actual API key
task_id = "your_task_id"  # Replace with your actual task ID

result = check_translation_status(task_id, api_key)

if result and result.get("status") == "SUCCESS":
    print(f"Use the Run ID: {result.get('run_id')} to fetch your translated result.")
```

This function demonstrates a robust implementation of status polling with several key features:

1. **Exponential backoff**: The wait time between requests starts small and gradually increases, which is efficient for both short and long-running tasks
2. **Multiple status handling**: Each possible status value is handled appropriately
3. **Error reporting**: Meaningful error messages help diagnose issues
4. **Progress tracking**: The elapsed time is displayed to keep users informed
5. **Timeout protection**: Both client-side and server-side timeouts are accounted for

By implementing a similar approach in your application, you can create a responsive user experience that keeps users informed about translation progress while efficiently managing system resources.

## When to Stop Polling

You should stop polling when you receive one of these definitive statuses:

* **`SUCCESS`**: You've received your translations
* **`ERROR`**: The task failed and won't recover
* **`TIMEOUT`**: The server timed out the request
* **`PAYMENT_REQUIRED`**: Payment issues need to be resolved

Only the **`PENDING`** status indicates that you should continue polling.

With this endpoint, you gain visibility into the translation process, allowing your application to respond appropriately based on real-time status information and retrieve completed translations as soon as they're available.


## OpenAPI

````yaml get /translate/{task_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /translate/{task_id}:
    get:
      tags:
        - Apis
      summary: Create translation Task Status
      operationId: translate_task_status_translate__task_id__get
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TaskIDParam'
            description: >-
              A unique identifier for the task. This is used to query the status
              of the translation task that is running. It is returned when a
              create request is made for translation.
      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:
    TaskIDParam:
      type: string
      title: Task ID
      description: >-
        This parameter represents a unique identifier for a task. It is used in
        various API endpoints to query the status or result of a specific task.
        The `task_id` is typically returned when a task is created.
    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.

````