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

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

Track the progression of your story creation process through systematic status checks. This endpoint provides granular visibility into each processing stage, enabling precise workflow management for time-sensitive applications.

This endpoint works in conjunction with the main [`/story`](create-story) endpoint, which initiates the dubbing process and provides the `task_id` needed for status checks.

## Checking Your Story Status

Let's explore how to effectively monitor your generation task using Python:

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

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

def check_story_status(task_id, polling_interval=5):
    """
    Monitors the status of a story generation task until completion.

    Parameters:
    - task_id: The unique identifier for your generation task
    - polling_interval: How frequently to check status (in seconds)

    Returns:
    - The final status response upon completion or failure
    """
    print(f"Beginning status monitoring for task: {task_id}")

    # Initialize tracking variables
    start_time = datetime.now()
    last_status = None

    while True:
        try:
            # Request the current status
            response = requests.get(
                f"https://client.camb.ai/apis/story/{task_id}",
                headers=headers
            )

            # Verify the request was successful
            response.raise_for_status()

            # Parse the status information
            status_data = response.json()
            current_status = status_data.get('status')

            # Track status changes for informative updates
            if current_status != last_status:
                elapsed_time = (datetime.now() - start_time).total_seconds()
                print(f"[{elapsed_time:.1f}s] Status: {current_status}")

                # Update our tracking variables
                last_status = current_status
                last_substatus = current_substatus

            # Check if the process has completed or failed
            if current_status == "SUCCESS":
                print("\n✓ Sound generation completed successfully!")
                print(f"Run ID : {status_data.get('run_id')}")
                return status_data
            elif current_status == "FAILED":
                print(f"\n✗ Sound generation failed: {status_data.get('message', 'Unknown error')}")
                return status_data


            # Wait before checking again
            time.sleep(polling_interval)

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

            # Brief pause before retry after error
            time.sleep(polling_interval)

# Example usage with intelligent polling
task_id = "your_task_id"  # Replace with your actual task_id
final_status = check_story_status(task_id, polling_interval=3)

# Process the completed result
if final_status and final_status.get('status') == "SUCCESS":
    print(f"Processing completed audio from: {audio_url}")

    # Download the generated audio
    audio_response = requests.get(audio_url)
    if audio_response.status_code == 200:
        print(f"Task completed successfully!, run ID {status_data.get('run_id')}")
```

## Best Practices for Status Monitoring

To efficiently track your dubbing tasks, consider these professional recommendations:

1. **Implement Exponential Backoff**: Start with frequent checks that gradually increase in interval to avoid overloading the API.
2. **Handle Terminal States**: Always implement proper handling for both successful completion and failure cases.

By properly integrating status checking into your application, you can create a seamless dubbing experience that keeps your users informed throughout the entire process.


## OpenAPI

````yaml get /story/{task_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /story/{task_id}:
    get:
      tags:
        - Apis
      summary: Get Story Status
      operationId: get_story_status_story__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 story task that is running. It is returned when a create
              request is made for a story.
      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.

````