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

# Get Project

> Retrieve details of a specific video project including processing status and download links

# Get Project

Retrieve detailed information about a specific video project, including its current processing status, metadata, and download links when available.

<Note>
  This endpoint requires authentication and has a rate limit of 100 requests per
  hour.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your Submagic API key starting with `sk-`
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier (UUID) of the project to retrieve
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the project (UUID format)
</ResponseField>

<ResponseField name="title" type="string">
  The title of the project
</ResponseField>

<ResponseField name="description" type="string">
  AI description of the project
</ResponseField>

<ResponseField name="language" type="string">
  Language code used for transcription
</ResponseField>

<ResponseField name="status" type="string">
  Current processing status: `processing`, `transcribing`, `exporting`,
  `completed`, or `failed`
</ResponseField>

<ResponseField name="webhookUrl" type="string">
  Webhook URL if provided in the request
</ResponseField>

<ResponseField name="templateName" type="string">
  Template name applied to the project (if using a built-in template)
</ResponseField>

<ResponseField name="userThemeId" type="string">
  User theme ID applied to the project (if using a custom theme)
</ResponseField>

<ResponseField name="presetId" type="string">
  Preset ID applied to the project (if using a preset)
</ResponseField>

<ResponseField name="aiEditTemplate" type="string">
  AI edit template applied to the project (if any): `kelly`, `karl`, or `ella`
</ResponseField>

<ResponseField name="downloadUrl" type="string">
  Direct download URL for the processed video (available when status is
  `completed`)
</ResponseField>

<ResponseField name="directUrl" type="string">
  Direct URL that can be embedded on your website or used to play the video
  directly (available when status is `completed`)
</ResponseField>

<ResponseField name="previewUrl" type="string">
  User-friendly preview page URL where the exported project can be previewed or
  downloaded: `https://app.submagic.co/view/{projectId}` (available when status
  is `completed`)
</ResponseField>

<ResponseField name="transcriptionStatus" type="string">
  Current transcription status: `PROCESSING`, `COMPLETED`, or `FAILED`
</ResponseField>

<ResponseField name="failureReason" type="string">
  Reason for failure if status is `failed`
</ResponseField>

<ResponseField name="magicZooms" type="boolean">
  Whether automatic zoom effects are enabled for the video
</ResponseField>

<ResponseField name="magicBrolls" type="boolean">
  Whether automatic B-roll insertion is enabled for the video
</ResponseField>

<ResponseField name="magicBrollsPercentage" type="number">
  Percentage of automatic B-rolls to include in the video (0-100)
</ResponseField>

<ResponseField name="removeSilencePace" type="string">
  Pace setting for automatic silence removal: `natural`, `fast`, or `extra-fast`
</ResponseField>

<ResponseField name="removeBadTakes" type="boolean">
  Whether automatic bad takes and silence removal is enabled
</ResponseField>

<ResponseField name="videoMetaData" type="object">
  Video metadata extracted from the source

  <Expandable title="Video Metadata" defaultOpen>
    <ResponseField name="width" type="number">
      Video width in pixels
    </ResponseField>

    <ResponseField name="height" type="number">
      Video height in pixels
    </ResponseField>

    <ResponseField name="duration" type="number">
      Video duration in seconds
    </ResponseField>

    <ResponseField name="fps" type="number">
      Frames per second (optional)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the project was created
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when the project was last updated
</ResponseField>

<ResponseField name="words" type="array">
  Array of transcribed words and silence segments with timing information (available when transcription is completed)

  <Expandable title="Word Object" defaultOpen>
    <ResponseField name="id" type="string">
      Unique identifier for the word or silence segment
    </ResponseField>

    <ResponseField name="text" type="string">
      The transcribed text content (empty string for silence segments)
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of segment: `word` for spoken words, `silence` for silent periods, or `punctuation` for punctuation marks
    </ResponseField>

    <ResponseField name="startTime" type="number">
      Start time of the word/silence in seconds
    </ResponseField>

    <ResponseField name="endTime" type="number">
      End time of the word/silence in seconds
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="magicClips" type="array">
  Array of generated Magic Clips (only present for Magic Clips projects)

  <Expandable title="Magic Clip Object" defaultOpen>
    <ResponseField name="id" type="string">
      Unique identifier for the Magic Clip (UUID format)
    </ResponseField>

    <ResponseField name="title" type="string">
      AI-generated title for the clip
    </ResponseField>

    <ResponseField name="duration" type="number">
      Duration of the clip in seconds
    </ResponseField>

    <ResponseField name="viralityScores" type="object">
      Object containing virality metrics for the clip (available when status is `completed`)

      <Expandable title="Virality Scores" defaultOpen>
        <ResponseField name="total" type="number">
          Overall virality score (0-100)
        </ResponseField>

        <ResponseField name="shareability" type="number">
          Shareability score (0-100)
        </ResponseField>

        <ResponseField name="hook_strength" type="number">
          Hook strength score (0-100)
        </ResponseField>

        <ResponseField name="story_quality" type="number">
          Story quality score (0-100)
        </ResponseField>

        <ResponseField name="emotional_impact" type="number">
          Emotional impact score (0-100)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="string">
      Processing status of the clip: `processing`, `completed`, or `failed`
    </ResponseField>

    <ResponseField name="previewUrl" type="string">
      URL to preview the Magic Clip (available when status is `completed`)
    </ResponseField>

    <ResponseField name="downloadUrl" type="string">
      Direct download URL for the Magic Clip (available when status is `completed`)
    </ResponseField>

    <ResponseField name="directUrl" type="string">
      Direct URL that can be embedded on your website or used to play the Magic Clip directly (available when status is `completed`)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: sk-your-api-key-here"
  ```

  ```javascript JavaScript theme={null}
  const getProject = async (projectId) => {
    const response = await fetch(
      `https://api.submagic.co/v1/projects/${projectId}`,
      {
        method: "GET",
        headers: {
          "x-api-key": "sk-your-api-key-here",
        },
      }
    );

    const project = await response.json();
    console.log("Project status:", project.status);
    return project;
  };

  // Usage
  const project = await getProject("550e8400-e29b-41d4-a716-446655440000");
  ```

  ```python Python theme={null}
  import requests

  def get_project(project_id):
      url = f'https://api.submagic.co/v1/projects/{project_id}'
      headers = {
          'x-api-key': 'sk-your-api-key-here'
      }

      response = requests.get(url, headers=headers)
      project = response.json()

      print(f"Project status: {project['status']}")
      return project

  # Usage
  project = get_project('550e8400-e29b-41d4-a716-446655440000')
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK - Transcribing theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Awesome Video",
    "description": "AI description of the project",
    "language": "en",
    "status": "transcribing",
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "templateName": "Hormozi 2",
    "transcriptionStatus": "PROCESSING",
    "magicZooms": true,
    "magicBrolls": true,
    "magicBrollsPercentage": 75,
    "removeSilencePace": "fast",
    "removeBadTakes": true,
    "videoMetaData": {
      "width": 1920,
      "height": 1080,
      "duration": 185.2,
      "fps": 30
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:32:15.000Z"
  }
  ```

  ```json 200 OK - Processing with Transcription Complete theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Awesome Video",
    "description": "AI description of the project",
    "language": "en",
    "status": "processing",
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "templateName": "Hormozi 2",
    "transcriptionStatus": "COMPLETED",
    "magicZooms": true,
    "magicBrolls": true,
    "magicBrollsPercentage": 75,
    "removeSilencePace": "fast",
    "removeBadTakes": true,
    "videoMetaData": {
      "width": 1920,
      "height": 1080,
      "duration": 185.2,
      "fps": 30
    },
    "words": [
      {
        "id": "silence_f9164d70-ac39-41cc-ae31-5b9de3093a2f",
        "text": "",
        "type": "silence",
        "startTime": 0,
        "endTime": 0.08
      },
      {
        "id": "w1EydrN5",
        "text": "Do",
        "type": "word",
        "startTime": 0.08,
        "endTime": 0.16
      },
      {
        "id": "8VUdYfGN",
        "text": "you",
        "type": "word",
        "startTime": 0.16,
        "endTime": 0.24
      },
      {
        "id": "eZBH24RB",
        "text": "mind",
        "type": "word",
        "startTime": 0.24,
        "endTime": 0.32
      },
      {
        "id": "RFLElgda",
        "text": "if",
        "type": "word",
        "startTime": 0.32,
        "endTime": 0.4
      },
      {
        "id": "iTWC5pc9",
        "text": "we",
        "type": "word",
        "startTime": 0.4,
        "endTime": 0.52
      },
      {
        "id": "EpT23tSM",
        "text": "do",
        "type": "word",
        "startTime": 0.52,
        "endTime": 0.68
      },
      {
        "id": "KtVZ8VDN",
        "text": "something",
        "type": "word",
        "startTime": 0.68,
        "endTime": 0.84
      },
      {
        "id": "LtVZ8CM",
        "text": "?",
        "type": "punctuation",
        "startTime": 0.84,
        "endTime": 0.84
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:35:20.000Z"
  }
  ```

  ```json 200 OK - Completed with Custom Theme theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Awesome Video",
    "description": "AI description of the project",
    "language": "en",
    "status": "completed",
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "userThemeId": "730e9500-f29c-52e5-b826-556755550001",
    "downloadUrl": "https://api.submagic.co/download/550e8400-e29b-41d4-a716-446655440000",
    "directUrl": "https://dqu1p08d61fh.cloudfront.net/api/9cc52d00-43d7-442f-9a22-050312bkm24f/1ddee5b4-101f-4c1e-a74a-b6b3bcfe206c/video.mp4-download.mp4",
    "previewUrl": "https://app.submagic.co/view/550e8400-e29b-41d4-a716-446655440000",
    "transcriptionStatus": "COMPLETED",
    "magicZooms": false,
    "magicBrolls": true,
    "magicBrollsPercentage": 30,
    "removeSilencePace": "natural",
    "removeBadTakes": false,
    "videoMetaData": {
      "width": 1920,
      "height": 1080,
      "duration": 185.2,
      "fps": 30
    },
    "words": [
      {
        "id": "silence_f9164d70-ac39-41cc-ae31-5b9de3093a2f",
        "text": "",
        "type": "silence",
        "startTime": 0,
        "endTime": 0.08
      },
      {
        "id": "w1EydrN5",
        "text": "Do",
        "type": "word",
        "startTime": 0.08,
        "endTime": 0.16
      },
      {
        "id": "8VUdYfGN",
        "text": "you",
        "type": "word",
        "startTime": 0.16,
        "endTime": 0.24
      },
      {
        "id": "eZBH24RB",
        "text": "mind",
        "type": "word",
        "startTime": 0.24,
        "endTime": 0.32
      },
      {
        "id": "RFLElgda",
        "text": "if",
        "type": "word",
        "startTime": 0.32,
        "endTime": 0.4
      },
      {
        "id": "iTWC5pc9",
        "text": "we",
        "type": "word",
        "startTime": 0.4,
        "endTime": 0.52
      },
      {
        "id": "EpT23tSM",
        "text": "do",
        "type": "word",
        "startTime": 0.52,
        "endTime": 0.68
      },
      {
        "id": "KtVZ8VDN",
        "text": "something",
        "type": "word",
        "startTime": 0.68,
        "endTime": 0.84
      },
      {
        "id": "LtVZ8CM",
        "text": "?",
        "type": "punctuation",
        "startTime": 0.84,
        "endTime": 0.84
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:45:30.000Z"
  }
  ```

  ```json 200 OK - Failed theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Awesome Video",
    "description": "AI description of the project",
    "language": "en",
    "status": "failed",
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "templateName": "Hormozi 2",
    "transcriptionStatus": "FAILED",
    "failureReason": "Video format not supported or file corrupted",
    "magicZooms": true,
    "magicBrolls": false,
    "magicBrollsPercentage": 50,
    "removeSilencePace": null,
    "removeBadTakes": false,
    "videoMetaData": {
      "width": 1920,
      "height": 1080,
      "duration": 185.2,
      "fps": 30
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:33:45.000Z"
  }
  ```

  ```json 200 OK - Magic Clips Project Completed theme={null}
  {
    "id": "e568c322-7fa5-497a-8fb0-3ba32e9e67d2",
    "title": "YT magic-clips test1",
    "description": "AI description of the project",
    "language": "en",
    "status": "completed",
    "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a19",
    "previewUrl": "https://app.submagic.co/view/e568c322-7fa5-497a-8fb0-3ba32e9e67d3",
    "transcriptionStatus": "COMPLETED",
    "videoMetaData": {
      "width": 1920,
      "height": 1080,
      "duration": 283,
      "fps": 30
    },
    "magicClips": [
      {
        "id": "5c26f199-08dd-4fab-911f-5378c23cc103",
        "title": "Fusion Camera Technology",
        "duration": 24.8,
        "viralityScores": {
          "total": 87,
          "shareability": 22,
          "hook_strength": 21,
          "story_quality": 22,
          "emotional_impact": 22
        },
        "status": "completed",
        "previewUrl": "https://app.submagic.co/view/5c26f199-08dd-4fab-911f-5378c23cc104",
        "downloadUrl": "https://api.submagic.co/api/file/download?path=3c6cd7cd-3f5e-4def-b662-69c48a7fc8ce/e568c322-7fa5-497a-8fb0-3ba32e9e67d2/5c26f199-08dd-4fac-911f-5378c23cc103-download.mp4&newFileName=Fusion%20Camera%20Technology.mp4",
        "directUrl": "https://dqu1p08d61fh.cloudfront.net/api/9cc52d00-43d7-442f-9a22-050312bkm24f/1ddee5b4-101f-4c1e-a74a-b6b3bcfe206c/video.mp4-download.mp4"
      },
      {
        "id": "364fe092-b68d-468a-9558-bfca7c4d190e",
        "title": "ProMotion Display Breakthrough",
        "duration": 21.04,
        "viralityScores": {
          "total": 89,
          "shareability": 23,
          "hook_strength": 22,
          "story_quality": 21,
          "emotional_impact": 23
        },
        "status": "completed",
        "previewUrl": "https://app.submagic.co/view/364fe092-b68d-468a-9558-bfca7c4d190g",
        "downloadUrl": "https://api.submagic.co/api/file/download?path=3c6cd7cd-3f5e-4def-b662-69c48a7fc8ce/e568c322-7fa5-497a-8fb0-3ba32e9e67d2/364fe092-b68d-468a-9558-bfca7c4d189c-download.mp4&newFileName=ProMotion%20Display%20Breakthrough.mp4",
        "directUrl": "https://dqu1p08d61fh.cloudfront.net/api/9cc52d00-43d7-442f-9a22-050312bkm24f/1ddee5b4-101f-4c1e-a74a-b6b3bcfe206c/video.mp4-download.mp4"
      }
    ],
    "createdAt": "2025-09-24T12:55:56.989Z",
    "updatedAt": "2025-09-24T12:59:24.880Z"
  }
  ```
</ResponseExample>