Get Translation Task Status

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}

• 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:

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.