> ## 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.

# Fetch Translation Results in Bulk

> Retrieves the final translated texts from multiple completed translation tasks using a list of `run_id` values in a single request.

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:

```json theme={null}
{
  "run_ids": [12345, 12346, 12347, 12348]
}
```

<Note>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.</Note>

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

```json [expandable] theme={null}
{
    "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:

```python [expandable] theme={null}
# 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

```python [expandable] theme={null}
# 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:

1. **Display them** to your users in organized, task-specific groups
2. **Store them** systematically with proper task organization
3. **Process them further** with additional NLP tools while maintaining task relationships
4. **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.


## OpenAPI

````yaml post /translation-results
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /translation-results:
    post:
      tags:
        - Apis
        - Translation
      summary: Get Translation Results
      operationId: get_translation_results_translation_results_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunIDsRequestPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkTranslationRunsResults'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    RunIDsRequestPayload:
      properties:
        run_ids:
          items:
            type: integer
            exclusiveMinimum: 0
          type: array
          maxItems: 5
          minItems: 2
          uniqueItems: true
          title: Run IDs
          description: >-
            An array of unique positive integers, each representing the ID of a
            specific run. You must provide between 2 and 5 IDs, and all IDs must
            correspond to the same run type (e.g., all text-to-speech or all
            dubbing runs).
          example:
            - 12345
            - 6789
      type: object
      required:
        - run_ids
      title: RunIDsRequestPayload
    BulkTranslationRunsResults:
      type: object
      title: BulkTranslationRunsResults
      additionalProperties:
        $ref: '#/components/schemas/TranslationResult'
      minProperties: 1
      maxProperties: 5
      description: >-
        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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TranslationResult:
      type: object
      properties:
        texts:
          description: >-
            An array of strings containing the translated output texts. Each
            item in the array corresponds to one translated text
          type: array
          items:
            type: string
          title: translated texts
      title: Translation Result
    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.

````