# Renders

> **Section:** [Introduction](https://docs.editsquare.com/api.md)
> **Related:** [Authentication](https://docs.editsquare.com/api/authentication.md) · [Errors](https://docs.editsquare.com/api/errors.md) · [Pagination](https://docs.editsquare.com/api/pagination.md) · [Webhooks](https://docs.editsquare.com/api/webhooks.md)
> **Also:** [HTML version](https://docs.editsquare.com/api/renders) · [Docs index](https://docs.editsquare.com/llms.txt)

---
A **render** is a video file produced from a project. When you create a
render, Edit Square takes the project as it exists at that moment, applies the
values you supply, and renders the result to a video file.

## Lifecycle

A render moves through the following statuses:

| Status | Meaning |
| --- | --- |
| `initializing` | The render was accepted and its configuration is being prepared. |
| `ready` | The configuration is prepared and the render is waiting for a worker. |
| `queued` | The render has been handed to a worker. |
| `processing` | The render is in progress. The first progress report moves it here. |
| `finalizing` | Rendering finished. The file is being stored and the credits charged. |
| `complete` | The render is finished. `output` carries the file URLs. |
| `failed` | The render stopped with an error. There is no output to collect. |

`complete` and `failed` are final; the other five are steps along the way.

## Applying values

`template_id` names a template defined in the project, and `values` is an
object keyed by that template's field keys.
For example, this template from
[Get a template](/api/reference/operations/gettemplate/) exposes a single
field, `customer_name`:

```json
{
  "id": "tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f",
  "name": "Welcome video",
  "fields": [
    {
      "key": "customer_name",
      "label": "Customer name",
      "default_value": "Acme"
    }
  ]
}
```

Each entry in `values` sets the field with the matching `key`. To render this
template for a customer named John Smith, the following would be used:

```json
{
  "name": "Welcome - John Smith",
  "project_id": "proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9",
  "template_id": "tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f",
  "values": { "customer_name": "John Smith" }
}
```

A field you leave out falls back to its `default_value` (`"Acme"` above), and
keys the template does not define are ignored. A `template_id` the project
does not define is an error, not a silent fall-through to the plain project.

The values are applied to a copy of the project configuration for this render
only. The project itself is untouched, so two renders from the same project
with different values never affect each other.

The full request body is documented in
[Create a render](/api/reference/operations/createrender/).

## Outputs

A `complete` render carries an `output` object of signed URLs, keyed by
variant: the master file, plus any smaller encodes the project produces.

The URLs are signed and time-limited. Download the file, or re-request the
render to get fresh URLs; they are not stable links to hand to a browser
weeks later.

The full response is documented in
[Get a render](/api/reference/operations/getrender/).

## Tracking a render

There are two ways to follow a render to completion:

- **Polling**: Request [`GET /v1/renders/{id}`](/api/reference/operations/getrender/) until the status is either
  `complete` or `failed`. This is simple and works well at small volume. A typical render takes a
  couple of minutes, so poll on that scale.
- **Webhooks**: Edit Square calls your endpoint when the render changes state.
  We recommend webhooks for anything unattended or at volume. See
  [Webhooks](/api/webhooks/).

## Listing renders

[`GET /v1/renders`](/api/reference/operations/listrenders/) lists a project's
renders, newest first. `project_id` is required: renders are listed per
project, not per team.