# Outputs and lifecycle

> Retrieve thumbnail files and manage their lifecycle.

Use webhooks to learn when processing finishes. Save the ID returned when you [generate thumbnails](/docs/thumbnails/quickstart) to match notifications or retrieve the current state when needed.

## Follow processing

| Status | Meaning |
| --- | --- |
| `preparing` | Thumbnail generation is queued or in progress. |
| `ready` | Processing and publication finished; the available files can be used. |
| `failed` | Processing failed. Read `error.code` and `error.message`. |
| `expired` | Temporary output files have expired and their delivery URLs are no longer available. |

Generation can finish with fewer samples than requested. Read `samples` to see what was produced. If no samples are published, generation fails. Correct the input or settings before generating thumbnails again.

## Receive webhook notifications

[Configure a webhook and verify its signature](/docs/integration/webhooks) before processing notifications. Standalone thumbnail events contain the resource snapshot in `data.thumbnail`.

| Event | Meaning |
| --- | --- |
| `thumbnail.created` | The thumbnail resource was created. |
| `thumbnail.ready` | The available thumbnails and their index were published. |
| `thumbnail.failed` | Processing failed. |
| `thumbnail.expired` | Temporary output files expired. |
| `thumbnail.deleted` | The resource was deleted, by you or on its scheduled `delete_at`. |

Webhooks can arrive more than once or out of order. Use the thumbnail ID to match notifications and retrieve the current state when needed.

Thumbnails created as Asset outputs use `aop_` IDs and `asset.output.*` events with the resource at `data.output.details`. Use the [Asset outputs API](/docs/video-streaming/outputs) to manage those outputs.

## Retrieve thumbnails

Retrieve thumbnails by ID when you need the current status or fresh temporary file URLs. Run this on your server using the client configured in the [quickstart](/docs/thumbnails/quickstart). Replace the example ID with the one you saved.

<codegroup>
<codeblock lang="TypeScript">
```typescript
const result = await client.thumbnails.retrieve(
    'thm_2G6MJiNz71bHQGNzGwKx5cJwPFS',
);

console.log(result.status, result.files, result.samples);
```
</codeblock>
<codeblock lang="Python">
```python
result = client.thumbnails.retrieve(
    "thm_2G6MJiNz71bHQGNzGwKx5cJwPFS",
)

print(result.status, result.files, result.samples)
```
</codeblock>
<codeblock lang="PHP">
```php
$result = $client->thumbnails->retrieve(
    'thm_2G6MJiNz71bHQGNzGwKx5cJwPFS',
);

var_dump($result->status, $result->files, $result->samples);
```
</codeblock>
<codeblock lang="Go">
```go
result, err := client.Thumbnails.Get(
	context.Background(),
	"thm_2G6MJiNz71bHQGNzGwKx5cJwPFS",
)
if err != nil {
	log.Fatal(err)
}

fmt.Println(result.Status, result.Files, result.Samples)
```
</codeblock>
</codegroup>

[List Thumbnails](/docs/api-reference/thumbnails/list-thumbnails) lets you find thumbnails by Source, output storage, status, or creation time.

## Use the files

The `files` collection includes images or sprite sheets and a WebVTT index. Use each file's `kind` to identify it:

| Kind | Contents |
| --- | --- |
| `image` | One thumbnail image. |
| `sprite` | A sheet containing several thumbnails. |
| `vtt` | A timeline index that points to images and, for sprites, their tile coordinates. |

Use an image's `cdn_url` for a poster or preview card. For timeline previews, pass the WebVTT file's `cdn_url` to your [player](/docs/integration/player).

Without a configured CDN, use the returned `url`. These temporary links expire after up to ten minutes; retrieve the thumbnails again to refresh them.

## Expiry and deletion

Thumbnails in Chunkify temporary storage expire 24 hours after publication, as shown by `expires_at`. They then become `expired` and their files are removed. Thumbnails in your storage don't expire.

Chunkify deletes standalone thumbnail records automatically. `delete_at` shows when, and a `thumbnail.deleted` event is sent:

| Status | Record deleted |
| --- | --- |
| `expired` | 3 days after the files expire. |
| `ready` in your storage | When your team's data retention period ends. |
| `failed` | When your team's data retention period ends. |

The data retention period is counted from when the thumbnails were requested. A record is always kept for at least 3 days after it becomes ready or fails.

Automatic deletion removes only the Chunkify record; it never deletes files in your storage. Thumbnails owned by an Asset follow that Asset instead.