<!-- Markdown twin of https://pixelvault.dev/docs/lifecycle/ -->

# Expiry & retention

Media you upload with an API key is permanent until you delete it, unless you ask for it to expire. This page covers every way an asset or a link to it can stop working.

Mechanism

What ends

When

[`expires_in`](#expires-in)

The asset and all its derivatives are deleted

After the TTL, at the next hourly sweep (up to about 2 hours late)

[Keyless upload](#keyless)

The anonymous image

30 days after upload

[`sign_expires_in` / `expires`](/docs/private-media/)

One signed link; the asset stays

Exactly at `expires`

Delete endpoint

The asset, its derivatives, and every link

Immediately

[Closing a `ci_build` collection](#collections)

Its members

At the next sweep

[Account and plan rules](#retention)

See below

## Auto-expiring uploads (`expires_in`)

Pass `expires_in` (60–2,592,000 seconds, i.e. 1 minute to 30 days) to have an asset deleted automatically. Anything else is `400 validation_error`; omit it for a permanent asset. It works on every upload path:

-   **Images**: a form field for file uploads, or a JSON field next to `url` for URL imports. Also accepted by [batch](/docs/api/images/#batch_upload), [generate](/docs/api/images/#generate_image) and [edit](/docs/api/images/#edit_image).
-   **Video**: `X-PixelVault-Expires-In` on direct uploads, `expires_in` in the JSON body for URL imports and resumable-upload initiation.
-   **Audio**: `X-PixelVault-Expires-In` on direct uploads, `expires_in` for URL imports.

```
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -F "file=@preview.png" \
  -F "expires_in=86400"

→ { "data": { "id": "img_abc123", "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
              "expires_in": 86400, "temporary": true } }
```

```
curl -X POST https://api.pixelvault.dev/v1/videos \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: video/mp4" \
  -H "X-PixelVault-Filename: preview.mp4" \
  -H "X-PixelVault-Expires-In: 604800" \
  --data-binary @preview.mp4
```

Images echo `"expires_in"` and `"temporary": true`; videos and audio report `expires_at` and `"temporary": true`.

### The hourly sweep

Deletion runs in a sweep at five past every hour (UTC). A few hourly runs are reserved for other maintenance and skip it, so removal can lag the TTL by up to about two hours. Don't use `expires_in` as an access control: until the sweep runs, the URL still serves. For exact cut-offs, make the asset [private](/docs/private-media/) and control the link lifetime instead.

When a video or audio asset expires, PixelVault fails any active optimization, enrichment or transcription job, returns its reserved monthly allowance, and deletes the original plus every derivative: poster, social-ready copy, transcripts, and storyboards. Unfinished resumable upload sessions are aborted after 24 hours by the same sweep, releasing their reserved quota. No video TTL default exists: video is permanent unless you set one.

## Keyless uploads

Image uploads without an API key are temporary: the response says `"expires_in": 2592000` and `"temporary": true`, and the image is removed 30 days after upload by a storage rule. To keep an image without that fixed expiration, re-upload it with your API key and use the new URL; the original anonymous URL still expires. Browser-tool uploads at [pixelvault.dev/tools](/tools/) without an account last up to 24 hours.

## Link expiry is not deletion

`sign_expires_in` (and the `expires_in` body of a `sign-url` call) only sets how long one signed link to a [private asset](/docs/private-media/) works. It never deletes bytes, and you can always mint a fresh link. Conversely, `expires_in` on upload deletes the asset no matter how many links are outstanding.

## Collections

Closing a collection with [`POST /v1/collections/:id/close`](/docs/api/collections/#close_collection) applies its cleanup policy: a closed `ci_build` collection's members are expired and removed by the next sweep. See [Collections](/docs/guides/organize-media/#collections).

## Account and plan retention

-   **Unverified accounts**: an account whose email is still unverified 30 days after signup is deleted with all of its media and keys. Verify the email to keep it.
-   **Free plan**: per the [terms](/terms/), free-plan images older than 6 months that haven't been accessed in 30 days may be cleaned up after a 14-day grace period.
-   **Paid plans** retain media indefinitely. After a downgrade to free, free-plan rules apply; see [Billing](/docs/billing/).
-   **Exports**: an export archive can be downloaded for 24 hours after it completes.

## Next steps

-   [Private media & signed URLs](/docs/private-media/).
-   [Export all media](/docs/guides/export-media/) before deleting a project.
-   [Rate limits & quotas](/docs/limits/).
