---
updatedAt: 2026-09-10T15:50:00.000Z
---

Fetch the complete documentation index at: https://docs.synthesia.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Retrieve a video

You can use Retrieve a video endpoint to pull for the video status.

# OpenAPI definition

```json
{
  "info": {
    "description": "Synthesia public API endpoints",
    "title": "Synthesia API",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.synthesia.io",
      "description": "Synthesia public API URL."
    }
  ],
  "paths": {
    "/v2/videos/{video_id}": {
      "get": {
        "summary": "Retrieve a video",
        "description": "You can use Retrieve a video endpoint to pull for the video status.",
        "tags": [
          "Videos"
        ],
        "security": [
          {
            "api_key": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "video_id",
            "description": "The video ID to retrieve",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VideoResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Wrong API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Video ID was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected Server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "openapi": "3.0.2",
  "components": {
    "schemas": {
      "CtaSettings": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Label for a call-to-action button.",
            "example": [
              "Learn More",
              "Sign up"
            ]
          },
          "url": {
            "type": "string",
            "pattern": "^(?:(?:(?:https?|ftp):)?//)?(?:\\S+(?::\\S*)?@)?(?:(?!(?:10|127)(?:\\.\\d{1,3}){3})(?!(?:169\\.254|192\\.168)(?:\\.\\d{1,3}){2})(?!172\\.(?:1[6-9]|2\\d|3[0-1])(?:\\.\\d{1,3}){2})(?:[1-9]\\d?|1\\d\\d|2[01]\\d|22[0-3])(?:\\.(?:1?\\d{1,2}|2[0-4]\\d|25[0-5])){2}(?:\\.(?:[1-9]\\d?|1\\d\\d|2[0-4]\\d|25[0-4]))|(?:(?:[a-z0-9\\u00a1-\\uffff][a-z0-9\\u00a1-\\uffff_-]{0,62})?[a-z0-9\\u00a1-\\uffff]\\.)+(?:[a-z\\u00a1-\\uffff]{2,}\\.?))(?::\\d{2,5})?(?:[/?#]\\S*)?$",
            "description": "URL to navigate to, when the call-to-action button is clicked.",
            "example": [
              "https://example.com",
              "https://signup.example.com"
            ]
          }
        },
        "required": [
          "label",
          "url"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "context": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "VideoThumbnailTypesResponse": {
        "type": "object",
        "properties": {
          "image": {
            "type": "string",
            "default": null,
            "nullable": true
          },
          "gif": {
            "type": "string",
            "default": null,
            "nullable": true
          }
        }
      },
      "VideoResponse": {
        "type": "object",
        "properties": {
          "callbackId": {
            "type": "string",
            "description": "Use callback ID to link videos back to the initial request. For example, if you are making a personalized video for a customer, you could enter the customer's email as a callback ID. This way, you can tell who the video is for, once its generated.."
          },
          "createdAt": {
            "type": "integer",
            "description": "UNIX timestamp representing the time video was created."
          },
          "ctaSettings": {
            "description": "Settings for a call-to-action button.",
            "allOf": [
              {
                "$ref": "#/components/schemas/CtaSettings"
              }
            ]
          },
          "description": {
            "type": "string",
            "default": "",
            "description": "Description of the video to be shown on the share page."
          },
          "test": {
            "type": "boolean",
            "default": false,
            "description": "Test videos are free and not counted towards your quota. If you create a video in the “test” mode, we will overlay a watermark over your video."
          },
          "download": {
            "type": "string"
          },
          "duration": {
            "type": "string"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "lastUpdatedAt": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "deleted",
              "error",
              "in_progress",
              "rejected",
              "approved"
            ]
          },
          "thumbnail": {
            "default": null,
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/VideoThumbnailTypesResponse"
              }
            ]
          },
          "title": {
            "type": "string",
            "default": "",
            "description": "Title of the video to be shown on the share page."
          },
          "visibility": {
            "type": "string",
            "default": "private",
            "enum": [
              "private",
              "public"
            ],
            "description": "Public videos will be visible to anyone with a share URL.\n\nPrivate videos can only be downloaded via a time-limited download link. See Retrieve a video for details.\n\nVisibility can be changed also once the video is created via Update a video."
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    }
  }
}
```

# Sibling pages

* [Create a video](https://docs.synthesia.io/reference/create-video.md)
* [Create a video from a template](https://docs.synthesia.io/reference/create-a-video-from-a-template.md)
* [List videos](https://docs.synthesia.io/reference/list-videos.md)
* [Retrieve a thumbnail](https://docs.synthesia.io/reference/retrieve-a-jpg-thumbnail.md)
* [Retrieve a GIF thumbnail](https://docs.synthesia.io/reference/retrieve-a-gif-thumbnail.md)
* [Retrieve a GIF/JPG thumbnail](https://docs.synthesia.io/reference/retrieve-a-gif-jpg-thumbnail.md)
* [Update a video](https://docs.synthesia.io/reference/update-a-video.md)
* [Delete a video](https://docs.synthesia.io/reference/delete-a-video.md)