> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transcribetube.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Project Detail

Fetch a single project's status and (if ready) its transcription text. Use this to poll for completion — see [Lifecycle & Polling](/api-documentation/lifecycle).

## Request

| Param               | In    | Type    | Default | Description                                                                                  |
| ------------------- | ----- | ------- | ------- | -------------------------------------------------------------------------------------------- |
| `id`                | path  | string  | —       | The `projectId` returned by `POST /api/transcribeVideo`.                                     |
| `showTimecode`      | query | boolean | `false` | Include `[HH:MM:SS.sss]` timecodes in the `text` field (only applies when state is `done`).  |
| `showSpeaker`       | query | boolean | `false` | Include `Speaker N:` labels in the `text` field.                                             |
| `showTranscription` | query | boolean | `true`  | If `false`, omits the full transcript JSON (currently ignored by the API view but reserved). |

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.transcribetube.com/api/detail/f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50" \
    -H "api-key: $TRANSCRIBETUBE_API_KEY"
  ```

  ```bash with options theme={null}
  curl "https://api.transcribetube.com/api/detail/f3c1e7a0-…?showTimecode=true&showSpeaker=true" \
    -H "api-key: $TRANSCRIBETUBE_API_KEY"
  ```

  ```js Node (fetch) theme={null}
  const res = await fetch(
    `https://api.transcribetube.com/api/detail/${projectId}`,
    { headers: { "api-key": process.env.TRANSCRIBETUBE_API_KEY } }
  );
  const project = await res.json();
  if (project.state === "done") {
    console.log(project.text);
  }
  ```
</CodeGroup>

## Response

The response shape **depends on the project's state**.

### When `state` is `done`

```json theme={null}
{
  "id": "f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50",
  "name": "Rick Astley - Never Gonna Give You Up",
  "youtubeId": "dQw4w9WgXcQ",
  "language": "en",
  "text": "We're no strangers to love\n\nYou know the rules and so do I\n\n..."
}
```

| Field       | Type   | Description                                                                                                                                                                   |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | string | Project ID.                                                                                                                                                                   |
| `name`      | string | Video title.                                                                                                                                                                  |
| `youtubeId` | string | The YouTube video ID.                                                                                                                                                         |
| `language`  | string | Language code.                                                                                                                                                                |
| `text`      | string | Plain-text transcription. Paragraphs separated by `\n\n`. With `showTimecode=true`, each paragraph is prefixed by `[HH:MM:SS.sss]`; with `showSpeaker=true`, by `Speaker N:`. |

<Note>
  The `done` shape does **not** include the `state` field. If you're branching on state, also check for the presence of `text` to confirm completion.
</Note>

### When `state` is `upload` or `transcription`

```json theme={null}
{
  "id": "f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50",
  "name": "Rick Astley - Never Gonna Give You Up",
  "state": "transcription",
  "message": "Transcription is in progress",
  "videoLength": 213,
  "createdAt": "2026-01-15T14:30:00.000Z"
}
```

| Field         | Type              | Description                   |
| ------------- | ----------------- | ----------------------------- |
| `state`       | enum              | `upload` or `transcription`.  |
| `message`     | string            | Human-readable status.        |
| `videoLength` | integer           | Length in seconds.            |
| `createdAt`   | string (ISO 8601) | When the project was created. |

## Errors

| Status | When                                                  |
| ------ | ----------------------------------------------------- |
| 401    | Missing or invalid `api-key` header.                  |
| 404    | Project not found, or it belongs to a different user. |


## OpenAPI

````yaml get /api/detail/{id}
openapi: 3.0.0
info:
  title: Transcribe Tube
  description: Welcome to the API Panel for Transcribe Tube
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.transcribetube.com
security: []
tags: []
paths:
  /api/detail/{id}:
    get:
      tags:
        - Api
      operationId: ApiController_findProjectById
      parameters:
        - name: id
          required: true
          in: path
          description: The ID of the project to retrieve
          schema:
            type: string
        - name: showTimecode
          in: query
          description: Show Timecode on content
          schema:
            type: boolean
            default: false
        - name: showSpeaker
          in: query
          description: Show Speaker name on content
          schema:
            type: boolean
            default: false
        - name: showTranscription
          in: query
          description: Show Transcription word by word
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Project detail. Shape depends on state.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ProjectDetailDone'
                  - $ref: '#/components/schemas/ProjectDetailInProgress'
        '401':
          description: Missing or invalid api-key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - api-key: []
components:
  schemas:
    ProjectDetailDone:
      type: object
      description: Returned when state is 'done'
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        youtubeId:
          type: string
        language:
          type: string
          example: en
        text:
          type: string
          description: Paragraphs joined by \n\n. Includes timecodes/speakers if requested.
    ProjectDetailInProgress:
      type: object
      description: Returned when state is 'upload' or 'transcription'
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        state:
          type: string
          enum:
            - upload
            - transcription
        message:
          type: string
          example: Transcription is in progress
        videoLength:
          type: integer
          description: Length in seconds
        createdAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key

````