Fetch Translation Results in Bulk

This endpoint delivers the final products of multiple translation processes simultaneously: all your translated texts in one efficient request. Once your translation tasks have completed successfully and you’ve received multiple run_id values, this endpoint allows you to retrieve all the actual translations that were generated. Think of it as the express pickup counter where you collect several finished translation orders at once, rather than making individual trips for each one.

How to Use This Endpoint

To retrieve multiple sets of translated texts, send a POST request to this endpoint with an array of run_id values in the request body. Each run_id serves as your claim ticket for a finished translation task. You must provide between 2 and 5 run_id values per request. The system will respond with a structured object containing all your translated texts, organized by their corresponding run_id values.

Request Format

The request body should contain an array of run_id values for the completed translation tasks you want to retrieve. You must provide between 2 and 5 run_id values per request:

{
  "run_ids": [12345, 12346, 12347, 12348]
}

The run_ids array must contain between 2 and 5 values. Requests with fewer than 3 or more than 5 run_ids will be rejected with a validation error.

Understanding the Response

When you call this endpoint, you’ll receive a response that includes all your translated content organized by run_id:

results: An object where each key is a run_id and each value contains the translation data for that specific task
texts: Within each result, an array of strings containing the translated output texts, maintaining the same order as the original input for that task

The structure of the response follows this format:

{
    "12345": {
      "texts": [
        "Your first translated text from task 12345",
        "Your second translated text from task 12345"
      ]
    },
    "12346": {
      "texts": [
        "Your first translated text from task 12346",
        "Your second translated text from task 12346",
        "Your third translated text from task 12346"
      ]
    },
    "12347": {
      "texts": [
        "Single translated text from task 12347"
      ]
    },
    "12348": {
      "texts": [
        "First text from task 12348",
        "Second text from task 12348",
        "Third text from task 12348",
        "Fourth text from task 12348"
      ]
    }
}

This structured response format makes it simple to process multiple translation tasks while maintaining clear organization. You can easily access translations for any specific task or iterate through all results systematically.

Working with Bulk Translation Results

There are several effective patterns for handling bulk translation results:

Direct Processing

For immediate use, you can extract and process all translation results:

# Welcome to the translation results retriever! 🌍✨
# This script will help you get translation results for multiple tasks from the Camb AI API.
# Make sure you have the requests library installed. If not, run: pip install requests 📦

import requests

# Set up the headers for the API request. This includes your API key and the content type. 🔑
# TODO: Replace 'your-api-key' with your actual API key from Camb AI.
headers = {
    "x-api-key": "your-api-key",  # Replace with your actual API key
    "Content-Type": "application/json",
}

# List of run_ids for the completed translation tasks you want to retrieve. 📋
# TODO: Replace these with your actual run_ids. Must be between 2 and 5 run_ids.
run_ids = [12345, 12346, 12347, 12348]  # Example run_ids


def get_bulk_translation_results(run_ids):
    """
    Retrieves translations for multiple completed tasks in a single request. 🚀

    Args:
        run_ids: List of run_id values for completed translation tasks (must be 3-5 items)

    Returns:
        dict: Dictionary mapping run_ids to their translation results
    """
    # Check if the number of run_ids is between 2 and 5. If not, print an error message and return an empty dictionary. ⚠️
    if len(run_ids) < 2 or len(run_ids) > 5:
        print(
            f"❌ Error: Must provide between 2 and 5 run_ids. You provided {len(run_ids)}."
        )
        return {}

    print(f"🌟 Retrieving translations for {len(run_ids)} completed tasks...")

    # Prepare the payload for the API request. This includes the list of run_ids. 📦
    payload = {"run_ids": run_ids}

    try:
        # Define the API endpoint URL. 🌐
        API_URL = "https://client.camb.ai/apis/translation-results"

        # Make the POST request to the API endpoint to retrieve the translation results. 🚀
        response = requests.post(API_URL, headers=headers, json=payload)

        # Check if the request was successful. If not, an exception will be raised. ✅
        response.raise_for_status()

        # Parse the JSON response to get the translation results. 📄
        results = response.json()

        print(f"🎉 Successfully retrieved translations for {len(results)} tasks!")
        return results

    except requests.exceptions.RequestException as e:
        print(f"😢 Oops! There was an error retrieving the translation results: {e}")
        return {}


# Now, let's retrieve the translation results for the provided run_ids. 🌟
translation_results = get_bulk_translation_results(run_ids)

# Check if any results were retrieved. If not, print a message. 🤔
if not translation_results:
    print(
        "😞 No translation results were retrieved. Please check your run_ids and API key."
    )
else:
    # Process the retrieved translation results and print them. 🖨️
    for run_id in translation_results:
        translations = translation_results.get(run_id, {}).get("texts", [])
        print(f"\n🎉 Run ID {run_id} has {len(translations)} translations:")
        for i, translation in enumerate(translations):
            print(f"  {i+1}. {translation} 🌍")

# What's next? You could save these results to a file or use them in your next project! 🚀

Best Practices

Request Size Requirements

This endpoint requires a specific batch size for optimal performance and resource management:

Minimum: You must provide at least 2 run_id values per request
Maximum: You can provide up to 5 run_id values per request
Validation: Requests outside this range will be rejected with a validation error

Handling Larger Datasets

If you have more than 5 completed translation tasks to retrieve:

Split into Multiple Requests: Divide your run_id list into chunks of 3-5 items
Sequential Processing: Process chunks sequentially to avoid rate limiting
Batch Management: Implement logic to group your run_ids efficiently

# Example: Processing larger datasets
all_run_ids = [12345, 12346, 12347, 12348, 12349, 12350, 12351, 12352]

# Split into chunks of 3-5 run_ids
def chunk_run_ids(run_ids, chunk_size=5):
    """Split run_ids into chunks of specified size (3-5)."""
    chunks = []
    for i in range(0, len(run_ids), chunk_size):
        chunk = run_ids[i:i + chunk_size]
        if len(chunk) >= 2:  # Ensure minimum chunk size
            chunks.append(chunk)
        elif chunks:  # Add remaining items to last chunk if possible
            chunks[-1].extend(chunk)
    return chunks

# Process in batches
chunks = chunk_run_ids(all_run_ids)
all_results = {}

for i, chunk in enumerate(chunks):
    print(f"Processing batch {i+1}/{len(chunks)}: {len(chunk)} run_ids")
    batch_results, failed_ids = get_bulk_translation_results_with_error_handling(chunk)
    all_results.update(batch_results)

Error Recovery

Always implement proper error handling when working with bulk operations:

Check response status codes before processing results
Handle partial failures gracefully (some run_ids may succeed while others fail)
Implement retry logic for transient failures
Log failed run_ids for later processing

Next Steps

Once you’ve retrieved your bulk translation results, you can:

Display them to your users in organized, task-specific groups
Store them systematically with proper task organization
Process them further with additional NLP tools while maintaining task relationships
Use them in your application logic to enable comprehensive multilingual functionality

The structured response format makes it easy to integrate multiple translation results wherever they’re needed in your workflow, whether you’re building a multilingual content management system, an educational platform with batch translation capabilities, or an international communication tool that processes multiple conversation threads. By understanding how to effectively use this bulk endpoint, you can create highly efficient multilingual applications that deliver multiple sets of high-quality translations to your users in a single, streamlined operation.

Authorizations

x-api-key

string

header

required

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.

Body

application/json

Response

Successful Response

An object containing the results of one to five transcription runs. Each key in the object is a unique identifier for a run, and the corresponding value is the translation output.

INTRODUCTION

API ENDPOINTS

ADMINISTRATION

Fetch Translation Results in Bulk

How to Use This Endpoint

Request Format

Understanding the Response

Working with Bulk Translation Results

Direct Processing

Best Practices

Request Size Requirements

Handling Larger Datasets

Error Recovery

Next Steps

Authorizations

Body

Response

INTRODUCTION

API ENDPOINTS

ADMINISTRATION

​How to Use This Endpoint

​Request Format

​Understanding the Response

​Working with Bulk Translation Results

​Direct Processing

​Best Practices

​Request Size Requirements

​Handling Larger Datasets

​Error Recovery

​Next Steps

Authorizations

Body

Response

How to Use This Endpoint

Request Format

Understanding the Response

Working with Bulk Translation Results

Direct Processing

Best Practices

Request Size Requirements

Handling Larger Datasets

Error Recovery

Next Steps