> ## 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 Subtitle Results

> Retrieves the results of multiple subtitle runs using the provided run IDs in the request body.

Fetches subtitle results for several runs in one request. Each run's value matches [Get Subtitle Result](get-subtitle-run-result): structured JSON by default, or exported `srt`/`vtt`/`txt` when you pass `format_type` and/or `data_type`.

* **By default** (no query params) each run returns structured JSON: one language → `{ "transcript": [ ... ] }`; many → object keyed by language ID.
* **When you pass `format_type` and/or `data_type`**, each run is exported the same way as [Get Subtitle Result](get-subtitle-run-result): one language → `{ "transcript": <url|text> }`; many → `{ "<lang_id>": { "transcript": <url|text> }, ... }`.

## Choosing your output

| Parameter            | Values                                                  | Behaviour                              |
| :------------------- | :------------------------------------------------------ | :------------------------------------- |
| *(none)*             | n/a                                                     | Per run: structured JSON transcript(s) |
| `data_type=file`     | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | Per run: presigned file URL(s)         |
| `data_type=raw_data` | `srt` / `vtt` / `txt` via `format_type` (default `txt`) | Per run: rendered text inline          |

Same `format_type` / `data_type` values as [Get Transcription Result](get-transcription-run-result) and [Get Subtitle Result](get-subtitle-run-result).

## Request

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

## Response Structure

The API returns an object keyed by `run_id`.

### Default (no export params)

```json [expandable] theme={null}
{
  "12345": {
    "transcript": [
      { "start": 0.0, "end": 2.5, "speaker": "SPEAKER_0", "text": "Welcome to our discussion on AI." }
    ]
  },
  "12346": {
    "1": {
      "transcript": [
        { "start": 0.0, "end": 2.5, "speaker": "SPEAKER_0", "text": "Welcome to our discussion on AI." }
      ]
    },
    "23": {
      "transcript": [
        { "start": 0.0, "end": 2.7, "speaker": "SPEAKER_0", "text": "Bienvenidos a nuestra discusión sobre IA." }
      ]
    }
  }
}
```

| Field     | Description                             |
| :-------- | :-------------------------------------- |
| `start`   | Start time of the segment (seconds)     |
| `end`     | End time of the segment (seconds)       |
| `text`    | Text for this segment, in that language |
| `speaker` | Speaker identifier                      |

### Export (`format_type` / `data_type`)

```json theme={null}
{
  "12345": { "transcript": "https://storage.example.com/.../output_transcript.srt?..." },
  "12346": {
    "1":  { "transcript": "https://storage.example.com/.../en_us/output_transcript.srt?..." },
    "23": { "transcript": "https://storage.example.com/.../es_es/output_transcript.srt?..." }
  }
}
```

<Info>Presigned file URLs expire after 24 hours.</Info>

## Implementation Example

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

headers = {
    "x-api-key": "your-api-key",
    "Content-Type": "application/json",
}

API_URL = "https://client.camb.ai/apis/sub-results"
run_ids = [12345, 12346, 12347, 12348]

# Default: structured JSON per run
bulk = requests.post(API_URL, headers=headers, json={"run_ids": run_ids}).json()
for run_id, run_result in bulk.items():
    if "transcript" in run_result:
        print(f"Run {run_id}: {len(run_result['transcript'])} segments")
    else:
        for language_id, payload in run_result.items():
            print(f"Run {run_id} / lang {language_id}: {len(payload['transcript'])} segments")

# Export: SRT file URLs for every language on every run
srt_bulk = requests.post(
    API_URL,
    headers=headers,
    params={"format_type": "srt", "data_type": "file"},
    json={"run_ids": run_ids},
).json()
for run_id, run_result in srt_bulk.items():
    if "transcript" in run_result:
        print(f"Run {run_id}: {run_result['transcript']}")
    else:
        for language_id, payload in run_result.items():
            print(f"Run {run_id} / lang {language_id}: {payload['transcript']}")
```

## Best Practices

* **Batch size**: at least 2 and at most 5 `run_id` values per request
* **Larger sets**: split into chunks of 3–5 and process sequentially to avoid rate limits

## Next Steps

1. [Get Subtitle Result](get-subtitle-run-result) for a single run (same export params)
2. [Get Subtitle Result for Language](get-subtitle-result-for-language) when you only need one language
3. [Create Subtitle](create-subtitle) to start a new run


## OpenAPI

````yaml post /sub-results
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /sub-results:
    post:
      tags:
        - Apis
        - Subtitles
      summary: Get Subtitle Results
      description: >-
        Bulk fetch subtitle results for multiple run IDs. Each run matches `GET
        /sub-result/{run_id}`: structured JSON by default, or exported
        `srt`/`vtt`/`txt` when `format_type` and/or `data_type` query params are
        set.
      operationId: get_subtitle_results_sub_results_post
      parameters:
        - name: format_type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/TranscriptFileFormat'
              - type: 'null'
            title: Format Type
          description: >-
            Subtitle format for the transcript export: `srt`, `vtt` or `txt`.
            When omitted (and `data_type` is also omitted) the structured JSON
            transcript is returned instead of an exported file. Applied to every
            language on each run.
        - name: data_type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/TranscriptDataType'
              - type: 'null'
            title: Data Type
          description: >-
            How the exported transcript is returned once
            `format_type`/`data_type` is set: `file` returns a presigned URL,
            `raw_data` returns the raw text. In export mode the effective
            defaults are `format_type=txt`, `data_type=file`. Applied to every
            language on each run.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunIDsRequestPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubtitleRunsResults'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TranscriptFileFormat:
      type: string
      enum:
        - srt
        - vtt
        - txt
      default: txt
      title: TranscriptFileFormat
    TranscriptDataType:
      type: string
      enum:
        - raw_data
        - file
      default: file
      title: TranscriptDataType
    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
    BulkSubtitleRunsResults:
      type: object
      title: BulkSubtitleRunsResults
      additionalProperties:
        $ref: '#/components/schemas/SubtitleRunResult'
      minProperties: 1
      maxProperties: 5
      description: >-
        An object containing the results of one to five subtitle runs. Each key
        is a run ID; each value matches `GET /sub-result/{run_id}` (JSON by
        default, or export when `format_type`/`data_type` are set).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SubtitleRunResult:
      title: Subtitle Run Result
      anyOf:
        - $ref: '#/components/schemas/SubtitleResult'
          title: Single Language
        - title: Multiple Languages
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SubtitleResult'
          description: >-
            Keyed by language ID, each value a SubtitleResult. Present when the
            run has more than one language.
      description: >-
        The result of a subtitle run: a single SubtitleResult when the run has
        one language, or an object keyed by language ID when it has multiple. In
        export mode (`format_type`/`data_type`), each `transcript` value is a
        presigned URL or raw text instead of a dialogue array.
    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
    SubtitleResult:
      type: object
      title: SubtitleResult
      properties:
        transcript:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/DialogueItem'
            - type: string
          description: >-
            Structured dialogue array by default; a string (presigned URL for
            `data_type=file`, or raw text for `data_type=raw_data`) in export
            mode.
      description: >-
        One language of a subtitle run: structured dialogue segments by default,
        or an exported transcript string when `format_type`/`data_type` are set.
    DialogueItem:
      type: object
      description: >-
        A JSON that represents a single piece of dialogue or speech within a
        given time range. It includes details about the timing (start and end),
        the content of the dialogue (text), and the speaker who delivers the
        dialogue
      properties:
        start:
          type: number
          format: float
          title: Start Time
          description: The start time (in seconds) of the dialogue.
        end:
          type: number
          format: float
          title: End Time
          description: The end time (in seconds) of the dialogue.
        text:
          type: string
          title: Dialogue Text
          description: The actual text content of the dialogue spoken by the speaker.
        speaker:
          type: string
          title: Speaker Name
          description: The name or identifier of the speaker delivering the dialogue.
      required:
        - start
        - end
        - text
        - speaker
      title: DialogueItem
  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.

````