# Retrieve a video

> The videos endpoint returns the status and the URL of a video by its id, or streams its progress again.

Canonical: https://bannerify.co/docs/api-reference/endpoint/get-video

## OpenAPI

```json get /v1/videos/{id}
{
  "openapi": "3.0.0",
  "info": {
    "title": "Bannerify API",
    "version": "0.0.0"
  },
  "servers": [
    {
      "url": "https://api.bannerify.co",
      "description": "Production"
    }
  ],
  "security": [
    {
      "token": []
    }
  ],
  "paths": {
    "/v1/videos/{id}": {
      "get": {
        "description": "Beta. Read a video of `POST /v1/templates/renderVideo` by its id: its status, and its URL once it is done. With `stream=true` the answer is the stream of its events, from the latest one, as `renderVideo` sends them. Use it to wait for a video again after the connection dropped.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "description": "The id of the video, from `renderVideo`."
            },
            "required": true,
            "description": "The id of the video, from `renderVideo`.",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "description": "Your API key. Create one on the API Keys page of the dashboard, and keep it on the server.",
              "example": "YOUR_API_KEY"
            },
            "required": true,
            "description": "Your API key. Create one on the API Keys page of the dashboard, and keep it on the server.",
            "name": "apiKey",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "`true` streams the events of the video as server-sent events.",
              "example": "true"
            },
            "required": false,
            "description": "`true` streams the events of the video as server-sent events.",
            "name": "stream",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "The video, or its events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "example": "vid_0b3c1c1e5d6f4c529e0a8f6a4c0f2a11"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "rendering",
                        "done",
                        "failed"
                      ],
                      "description": "`queued` while the video waits for a renderer, `rendering` while its frames render, then `done` or `failed`."
                    },
                    "url": {
                      "type": "string",
                      "description": "The public URL of the MP4, once the video is `done`.",
                      "example": "https://images.bannerify.co/files/0b3c1c1e-5d6f-4c52-9e0a-8f6a4c0f2a11.mp4"
                    },
                    "error": {
                      "type": "string",
                      "description": "Why the video `failed`."
                    }
                  },
                  "required": [
                    "id",
                    "status"
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "example": "event: done\ndata: {\"type\":\"done\",\"url\":\"https://images.bannerify.co/files/0b3c.mp4\"}\n\n"
                }
              }
            }
          },
          "400": {
            "description": "The request cannot be processed. BAD_REQUEST means a field is invalid, the API key is unknown, or a signed URL has a wrong signature. FETCH_IMAGE_ERROR means Bannerify could not download an image from a src URL. A rate limit on the PDF and stored endpoints also uses status 400 with the code TOO_MANY_REQUESTS. Read error.code to tell them apart.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrBadRequest"
                    },
                    {
                      "$ref": "#/components/schemas/ErrFetchImageError"
                    },
                    {
                      "$ref": "#/components/schemas/ErrTooManyRequests"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The template does not exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrNotFound"
                }
              }
            }
          },
          "500": {
            "description": "The server could not finish the request. INTERNAL_SERVER_ERROR means an unexpected failure, such as a render error or a failed upload to your S3 bucket. USAGE_EXCEEDED means your workspace reached its daily or monthly generation limit, and RATE_LIMITED means the API key sent too many requests. Read error.code to tell them apart.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrInternalServerError"
                    },
                    {
                      "$ref": "#/components/schemas/ErrUsageExceeded"
                    },
                    {
                      "$ref": "#/components/schemas/ErrRateLimited"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrBadRequest": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "BAD_REQUEST"
                ],
                "description": "A machine readable error code.",
                "example": "BAD_REQUEST"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/BAD_REQUEST"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrFetchImageError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "FETCH_IMAGE_ERROR"
                ],
                "description": "A machine readable error code.",
                "example": "FETCH_IMAGE_ERROR"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/FETCH_IMAGE_ERROR"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrTooManyRequests": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "TOO_MANY_REQUESTS"
                ],
                "description": "A machine readable error code.",
                "example": "TOO_MANY_REQUESTS"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/TOO_MANY_REQUESTS"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrNotFound": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "NOT_FOUND"
                ],
                "description": "A machine readable error code.",
                "example": "NOT_FOUND"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/NOT_FOUND"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrInternalServerError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "INTERNAL_SERVER_ERROR"
                ],
                "description": "A machine readable error code.",
                "example": "INTERNAL_SERVER_ERROR"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/INTERNAL_SERVER_ERROR"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrUsageExceeded": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "USAGE_EXCEEDED"
                ],
                "description": "A machine readable error code.",
                "example": "USAGE_EXCEEDED"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/USAGE_EXCEEDED"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "ErrRateLimited": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "RATE_LIMITED"
                ],
                "description": "A machine readable error code.",
                "example": "RATE_LIMITED"
              },
              "docs": {
                "type": "string",
                "description": "A link to our documentation with more details about this error code",
                "example": "https://bannerify.co/docs/api-reference/errors/code/RATE_LIMITED"
              },
              "message": {
                "type": "string",
                "description": "A human readable explanation of what went wrong"
              },
              "requestId": {
                "type": "string",
                "description": "Please always include the requestId in your error report",
                "example": "req:1234"
              }
            },
            "required": [
              "code",
              "docs",
              "message",
              "requestId"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}
```

## Related

- [Previous: Render a video](https://bannerify.co/docs/api-reference/endpoint/render-video)
- [Next: Render a signed URL](https://bannerify.co/docs/api-reference/endpoint/signed-url)
- [Documentation index](https://bannerify.co/docs/llms.txt)